Crawler Import Service
Description
This service is used to simplify importing data to ATOLLON. In ATOLLON, it's possible to add more complex business logic based on request type and it's parameters. External developers are let go of understanding ATOLLON's blackbox.
Request
POST https://<HOST>/crab/crawler/<request_type>?instance=<instance_name>
Contact
Create contact (person or company) with (optionally) contact folder identified by context category (FPATypeCategory).
Request
POST https://<HOST>/crab/crawler/contact?instance=<instance_name>
Data in JSON format:
{
"person": {
"firstName": "<name>",
"lastName": "<surname>",
"prefixTitle": "<prefixTitle>",
"postfixTitle": "<postfixTitle>",
"companyPersonRelation": [{
"companyExternalId": [{
"system": "<system1>",
"id": "<Company contact external ID>"
}],
"positionDesc": "<Position of person in company>",
"companyName": "<Name of the related company>",
"departmentName": "<Name of department>"
}]
},
"company": {
"companyName": "<company name>",
"companyCompanyRelation": [{
"companyExternalId": [{
"system": "<system1>",
"id": "<Company contact external ID>"
}],
"relationType": "<Relation type Mother company>"
}]
},
"address": [{
"street": "<street + number>",
"city": "<city name>",
"zip": "<zip text>",
"region": "<region name>",
"country": "<country name>",
"addressType": "<address type1>"
},
{
"street": "<street + number>",
"city": "<city name>",
"zip": "<zip text>",
"region": "<region name>",
"country": "<country name>",
"addressType": "<address type2>"
}
],
"contacts": {
"email": [{
"contact": "<email1>",
"contactInfoTypeName": ""
}, {
"contact": "<email2>",
"contactInfoTypeName": ""
}],
"phone": [{
"contact": "<telefon1>",
"contactInfoTypeName": ""
}, {
"contact": "<telefon2>",
"contactInfoTypeName": ""
}],
"mobile": [{
"contact": "<mobil1>",
"contactInfoTypeName": ""
}, {
"contact": "<mobil2>",
"contactInfoTypeName": ""
}],
"web": [{
"contact": "<web1>",
"contactInfoTypeName": ""
}, {
"contact": "<web2>",
"contactInfoTypeName": ""
}]
},
"description": "<Contact text field>",
"contactGroup": [{
"name": "<Group 1>",
"description": "<description>"
}, {
"name": "<Group 2>",
"description": "<descritpion>"
}],
"contactFolder": [{
"category": "<string1>",
"refId": "",
"parentFolder": {
"category": "<string1>",
"refId": "<string>",
"contactExternalId": [{
"system": "<system1>",
"id": "<Company contact external ID>"
}]
},
"responsibleUser": [{
"userName": "<user@workspace>",
"userRoleName": "<User Role>",
"primary": true
}]
}],
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<system2>",
"id": "<Contact old id>"
}],
"regNo": "<registered number of business>",
"vatNo": "<VAT number>",
"trackingCode": "<string>",
"source": "<original - your system ident>",
"industries": [{
"name": "<industry name>",
"description": "<industry description>"
}]
}Response
on SUCESS
- contactId
- folderId
- contact.externalId
Function progress
- Person is filled? => contact is "Person contact" (and the person is representative of the company), otherwise it's "Company contact" (either company or person surname is required)
Company contact
- Check whether company is existing (company name matches some record in DB) // see: https://help.atollon.com/books/backend-development/page/modcontact#bkmrk-%C2%A0
- If company does not exist, create new contact (company)
- Contact info and address is stored with company contact
- With company contact id, check whether contact has the desired contact folder. Desired contact folder is folder with FPATypeCategory (see list below)c. If the lead folder does not exist, it is created.
- If contactFolderCategory is not filled-in, the contact folder is not created.
- contactGroup - find the contact group with the same name. If the contact group does not exist, create it. Assign the contact to the group
Person contact
- Check whether person is existing (based on e-mail, mobile / if these are not filled-in, the person is created anyway). E-mail and mobile is stored with person contact
- Contact info and address is stored with person contact
- With person contact id, check whether contact has the desired contact folder. Desired contact folder is folder with FPATypeCategory of the client, lead, supplier, partner, etc. folder types. If the lead folder does not exist, it is created.
- If contactFolderCategory is not filled-in, the contact folder is not created.
- contactGroup - find the contact group with the same name. If the contact group does not exist, create it. Assign the contact to the group
- employer - if company oldId is found in companyPersonRelation, make binding, otherwise if companyName is filled-in in companyPersonRelation, company based on it's name or create new company contact and create binding
After the request is imported successfully, change the TIF status to "2".
Creating contact folder (client, supplier, etc.)
Contact folders is main building block in contact relations (ATOLLON's context).
Some useful context categories for contact folders used:
| Client | com.atollon.project.fpatypecategory.client |
| Supplier | com.atollon.project.fpatypecategory.supplier |
| Lead (potential client) | com.atollon.leads.fpatypecategory.lead |
| Partner | com.atollon.project.fpatypecategory.partner |
ExternalId
Please note that within Contact service, the system + externalId must be unique key.
Product
https://<HOST>/crab/crawler/product?instance=<instance_name>
POST data in JSON format:
{
"name": "<Product name>",
"refId": "<Product code>",
"description": "<Product description>",
"typeName": "<Product typee = Product, Service, Technology ...>",
"defaultQuantity": 1.0000,
"unitPrice": 4990.00,
"unitPriceCurrencyName": "<CZK, USD, etc.>",
"statusName": "<Product status = Active, Inactive>",
"unitsName": "<Product units = ks, md, hrs>",
"vatRateName": "<15 %, 21%, etc.>",
"openingBalanceQty": 0.0000,
"openingBalanceDate": "<2022-09-09T10:10>" // <now> datetime is default, if not provided,
"externalId": [
{
"system": "<system1>",
"id": "<ABCD-EFGH-ijkl-...>"
}, {
"system": "<sytem2>",
"id": "<ABCD-EFGH-ijkl-...>"
}
]
}Response
on SUCCESS
- productId
- productName
- productRefid
- product.externalId
Function progress
- Find product based on it's externalId OR code + product name, if this does not match, create product
- If existing product is found, values are updated, ie openingBalanceQty
Billing
To export service activities that include billing items, get the following resource:
Request
GET https://<HOST>/crab/crawler/billing?billingStatus=ToBeInvoiced&instance=<instance_name>
Response
[{
"activity": {
"id": "0123000",
"name": "<Activity name>",
"refId": "<Activity REF ID>",
"statusName": "<Activity custom status name>",
"description": "<Activity notes>",
"created": "<2022-09-01T00:00>",
"modified": "<2022-09-14T10:00>"
},
"project": {
"id": "<project id>",
"name": "<Project name>",
"refId": "<Project REF ID>",
"statusName": "<Activity custom status name>",
"description": "<Activity notes>",
"created": "<2022-09-01T00:00>",
"modified": "<2022-09-14T10:00>"
},
"folder": {
"name": "<Folder name>",
"refId": "<Folder REF ID>"
},
"contact": {
"person": {
"firstName": "<name>",
"lastName": "<surname>"
},
"company": {
"companyName": "<company name>"
},
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<sytem2>",
"id": "<Contact old id>"
}],
"regNo": "<registered number of business>",
"vatNo": "<VAT number>"
},
"customer": {
"name": "<Folder name>",
"refId": "<Folder REF ID>"
},
"customerContact": {
"person": {
"firstName": "<name>",
"lastName": "<surname>"
},
"company": {
"companyName": "<company name>"
},
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<sytem2>",
"id": "<Contact old id>"
}],
"regNo": "<registered number of business>",
"vatNo": "<VAT number>"
},
"billingItems": [{
"id": "123456",
"productName": "<Product name1>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"billingStatus": "ToBeInvoiced",
"billingType": 1,
"productExternalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}]
}, {
"id": "123457",
"productName": "<Product name2>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"billingStatus": "ToBeInvoiced",
"billingType": 2,
"productExternalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}]
}],
"documents": [{
"name": "<Document name>",
"id": "123"
}, {
"name": "<Document name2>",
"id": "456"
}]
}]Download documents
GET https://<HOST>/crab/crawler/download_document?docId=123123&instance=<instance_name>
You get file in response.
Update billing status of billing items
Run after you have processed the billing items from activity.
You can change status of each of the billing items. If billing items are marked as Invoiced, you can change either activity or project status. Activity status will be changed only if there are no remaining billing items to be invoiced.
Request
PUT https://<HOST>/crab/crawler/billing?instance=<instance_name>
DATA:
[{
"activity": {
"id": "0123000",
"statusName": "<Activity custom status name>"
},
"project": {
"id": "<project id>",
"statusName": "<Project custom status name>"
},
"billingItems": [{
"id": "123456",
"billingStatus": "Billed"
}, {
"id": "123457",
"billingStatus": "Cancelled"
}]
}]Billing states:
| 0 |
SalesItems
|
| 1 |
Pending
|
| 2 |
ForApproval
|
| 3 |
ToBeInvoiced
|
| 4 |
Billed
|
| 5 |
ApprovedByClient
|
| 6 |
Postponed
|
| 7 |
Cancelled
|
Billing types:
| 1 |
BillingItems
|
| 2 |
TimeSheetItems
|
Folder
Request
GET https://api.atollon.com/api/folders?contextCategory=com.atollon.leads.fpatypecategory.lead&limit=10Parameters
| Parameter | Type | Description |
|---|---|---|
contextCategory |
string | Optional. Filters folders by type category (e.g., com.atollon.leads.fpatypecategory.lead) |
limit |
integer | Optional. Number of results per page (default: 50) |
offset |
integer | Optional. Results offset for pagination |
search |
string | Optional. Search by folder name, contact name, or externalId |
Response
{
"folders": [
{
"folder": {
"refId": "F12345",
"name": "New Website Inquiry",
"typeName": "Klient"
},
"contact": {
"contactId": "C67890",
"externalId": [
{
"system": "test",
"id": "123"
}
],
"company": {
"name": "ABC studio 2 s.r.o.",
"regNumber": "",
"VATNumber": ""
},
"form": {
"Budget": "10000",
"Interested Service": "Web Development"
}
}
}
],
"total": 1,
"limit": 50,
"offset": 0
}Request
GET https://<HOST>/crab/crawler/folder_sample?instance=<instance_name>&id=<folder_id
Response
{
"folder": {
"refId": "<folder refid>",
"name": "<folder name>",
"typeName": "<folde type name> Klient, ...",
},
"contact": {
"externalId": [
{
"system": "test",
"id": "123"
}
],
"company": {
"name": "ABC studio 2 s.r.o.",
"regNumber": "",
"VATNumber": ""
}
"form": {
"<formitename1>": "<formitemvalue1>",
"<formitemname2>": "<formitemvalue2>"
}
}Request
Create new folder:
POST https://<HOST>/crab/crawler/folder?instance=<instance_name>
{
"folder": {
"refId": "<folder refid>",
"name": "<folder name>",
"typeName": "<folde type name> Klient, ...",
},
"contact": {
"externalId": [
{
"system": "test",
"id": "123"
}
],
"company": {
"name": "ABC studio 2 s.r.o.",
"regNumber": "",
"VATNumber": ""
}
"form": {
"<formitename1>": "<formitemvalue1>",
"<formitemname2>": "<formitemvalue2>"
}
}Project
Request
GET https://<HOST>/crab/crawler/project?instance=<instance_name>&id=<project_id
Response
{
"project": {
"aclh": "TREE000000216556",
"created": "2023-01-25T12:47:34.678428",
"createdByName": "admin@pioneer",
"customState": 132541101,
"defaultMessageContainer": 723389101,
"defaultMessageContainerPath": "Root > pioneer > Pioneer CRM Demo > ABC studio 2 s.r.o. > project test 1 > Activity > Unsorted",
"defaultMessageGroup": 723388101,
"folder": 673304101,
"folderName": "ABC studio 2 s.r.o.",
"folderTypeName": "Klient",
"formValues": 723392101,
"id": 723387101,
"isMasterProject": true,
"modified": "2023-01-25T14:42:04.329141",
"name": "project test 1",
"projectType": 149482101,
"provider": 132307101,
"providerName": "Pioneer CRM Demo",
"refId": "00005 - SUPPORT",
"state": 2,
"priority": 1.0,
"externalId": [
{
"externalSystem": "test",
"externalId": "project_test_1"
}
]
},
"contact": {
"person": {
"firstName": "<name>",
"lastName": "<surname>"
},
"company": {
"companyName": "<company name>"
},
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<sytem2>",
"id": "<Contact old id>"
}]
}
}Request
Create new project and add technology items:
POST https://<HOST>/crab/crawler/project?instance=<instance_name>
{
"project": {
"id": "<project id>",
"name": "<Project name>",
"refId": "<Project REF ID>",
"statusName": "<Activity custom status name>",
"description": "<Activity notes>",
"created": "<2022-09-01T00:00>",
"modified": "<2022-09-14T10:00>",
"category": "anyProjectCategory",
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<system2>",
"id": "<Contact old id>"
}],
"dimension1Name": "<dimension1Name>",
"dimension2Name": "<dimension2Name>",
"dimension3Name": "<dimension3Name>",
"customer": {
"contactExternalId": [{
"system": "<system1>",
"id": "<customer contact externalid>"
}],
"contextCategory": "anyFolderCategory"
}
},
"folder": {
"name": "<Folder name>",
"refId": "<Folder REF ID>",
"typeName": "<folder type name>",
"category": "anyFolderCategory"
},
"contact": {
"person": {
"firstName": "<name>",
"lastName": "<surname>"
},
"company": {
"companyName": "<company name>"
},
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<sytem2>",
"id": "<Contact old id>"
}],
"regNo": "<registered number of business>",
"vatNo": "<VAT number>"
},
"technologyItems": [{
"id": "123456",
"productName": "<Product name1>",
"productRefid": "<Product code>",
"name": "<Technology item text>",
"description": "<Technology item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"refId":"<Serial number>",
"externalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}],
"supplier": {
"contactExternalId": [{
"system": "test",
"id": "123"
}]
}
}, {
"id": "123457",
"productName": "<Product name2>",
"productRefid": "<Product code>",
"name": "<Technology item text>",
"description": "<Technology item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"refId":"<Serial number>",
"externalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}]
}],
"formValues": {
"<textFormItemName>": "hello",
"<numberFormItemName>": 22,
"<dateFormItemName>": "2023-05-23T00:00:00"
}
}Internal Procedure
- Based on given contact external id, find existing contact, if no contact is found, say ERR
- Based on folder.category, find whether folder for given contact is found, if not, create new contact folder
- Create new project into given category
- Load new technologyItems into the new project (technology items are projectItems with type = 3)
Request
Update project status:
PUT https://<HOST>/crab/crawler/project?instance=<instance_name>
{
"project": {
"id": "<project id>",
"name": "<Project name>",
"refId": "<Project REF ID>",
"statusName": "<Activity custom status name>",
"description": "<Activity notes>",
"created": "<2022-09-01T00:00>",
"modified": "<2022-09-14T10:00>",
"category": "anyProjectCategory",
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<system2>",
"id": "<Contact old id>"
}],
"dimension1Name": "<dimension1Name>",
"dimension2Name": "<dimension2Name>",
"dimension3Name": "<dimension3Name>",
"customer": {
"contactExternalId": [{
"system": "<system1>",
"id": "<customer contact externalid>"
}],
"contextCategory": "anyFolderCategory"
}
},
"technologyItems": [],
"formValues": {}
}Activity
GetActivity
Request
GET https://<HOST>/crab/crawler/activity?instance=<instance_name>&id=<activity_id>
Optional url param billingStatus for activity including billing items
Response
{
"acl": "TREE000000228302",
"aclh": "TREE000000228302",
"activityType": 449312101,
"activityTypeName": "Pravideln\\u00fd servis",
"created": "2023-08-01T16:53:14.198186",
"createdByName": "admin@pioneer",
"customState": 132412101,
"defaultMessageContainer": 773533101,
"defaultMessageContainerPath": "ABC DESIGN Branch > Servisn\\u00ed projekt > Activity > Pravideln\\u00fd servis",
"defaultMessageGroup": 773226101,
"folder": 773157101,
"folderName": "ABC DESIGN Branch",
"folderTypeName": "Company Branch",
"customer": {
"contactExternalId": [
{
"system": "<system1>",
"id": "<customer contact externalid>"
}
]
},
"supplier": {
"contactExternalId": [
{
"system": "<system1>",
"id": "<customer contact externalid>"
}
]
},
"formId": 449320101,
"formName": "Service Activity",
"formValues": 773535101,
"id": 773533101,
"modified": "2023-08-01T17:30:14.828457",
"modifiedByName": "admin@pioneer",
"name": "Pravideln\\u00fd servis",
"project": 773225101,
"projectName": "Servisn\\u00ed projekt",
'projectExternalId': [
{
"system": "<system1>",
"id": "<project externalid>"
}
],
"refId": "0348",
"state": 1,
"requestHash": "NULL",
"startDate": "2024-09-01T00:00:00.000000",
"finalDate": "2026-01-31T00:00:00.000000",
"dimension1Name": "China",
"dimension2Name": "Mobile",
"dimension3Name": "Internal",
"EXTERNAL_CONTACTS": {
"count": 0,
"EXTERNAL_CONTACT": []
}
"documents": [{
"name": "<Document name>",
"id": "123"
}, {
"name": "<Document name2>",
"id": "456"
}]
}ListActivity
Request
Response
[
{
"id": 773460101,
"name": "Pravideln\u00fd servis",
"type": 449312101,
"typeName": "Pravideln\u00fd servis",
"state": 3,
"customState": 132416101,
"customStateName": "Closed",
"created": "2023-08-01T15:55:56.385675",
"createdBy": 131750101,
"createdByName": "admin@pioneer",
"modified": "2023-08-01T16:53:11.718562",
"modifiedBy": 131750101,
"modifiedByName": "admin@pioneer",
"organization": 130946101,
"folder": 773157101,
"folderName": "ABC DESIGN Branch",
"folderParentId": 700827101,
"folderParentName": "ABC DESIGN",
"project": 773225101,
"projectName": "Servisn\u00ed projekt",
"refId": "0347",
"requestHash": "NULL",
"defaultMessageContainer": 773460101,
"defaultMessageGroup": 773226101,
"formId": 449320101,
"formValues": 773462101,
"startDate": "2023-04-01T00:00:00.000000",
"finalDate": "2024-08-31T00:00:00.000000",
"dimension1Name":"China",
"dimension2Name":"Mobile",
"dimension3Name":"Internal",
},
{
"id": 773533101,
"name": "Pravideln\u00fd servis",
"type": 449312101,
"typeName": "Pravideln\u00fd servis",
"state": 1,
"customState": 132412101,
"customStateName": "Initial",
"created": "2023-08-01T16:53:14.198186",
"createdBy": 131750101,
"createdByName": "admin@pioneer",
"modified": "2023-08-01T17:30:14.828457",
"modifiedBy": 131750101,
"modifiedByName": "admin@pioneer",
"organization": 130946101,
"folder": 773157101,
"folderName": "ABC DESIGN Branch",
"folderParentId": 700827101,
"folderParentName": "ABC DESIGN",
"project": 773225101,
"projectName": "Servisn\u00ed projekt",
"refId": "0348",
"requestHash": "NULL",
"defaultMessageContainer": 773533101,
"defaultMessageGroup": 773226101,
"formId": 449320101,
"formValues": 773535101,
"startDate": "2024-09-01T00:00:00.000000",
"finalDate": "2026-01-31T00:00:00.000000",
"dimension1Name":"China",
"dimension2Name":"Mobile",
"dimension3Name":"Internal",
}
]CreateActivity
Request
POST https://<HOST>/crab/crawler/activity?instance=<instance_name>
{
"activity": {
"name": "Pravidelný servis",
"refId": "0348",
"category": "<Activity category>",
"typeName": "Pravidelný servis",
"statusName": "In Progress",
"requestHash": "NULL",
"startDate": "2024-09-01T00:00:00.000000",
"finalDate": "2026-01-31T00:00:00.000000"
},
"project": {
"id": "<project id>",
"name": "<Project name>",
"refId": "<Project REF ID>",
"typeName": "<Project type name>",
"externalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<system2>",
"id": "<Contact old id>"
}
]
},
"servicedItems": [
{
"productName": "<Product name1>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"refId": "<Billing item refid text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"vatValue": 21.0,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"productExternalId": [
{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<system2>",
"id": "<Product old id>"
}
]
}, {
"productName": "<Product name2>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"refId": "<Billing item refid text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"vatValue": 21.0,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"productExternalId": [
{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<system2>",
"id": "<Product old id>"
}
]
}
],
"formValues": {}
}UpdateActivity
Request
PUT https://<HOST>/crab/crawler/activity?instance=<instance_name>
{
"activity": {
"id": "<activity_id>",
"name": "Pravideln\u00fd servis",
"refId": "0348",
"statusName": "In Progress",
"requestHash": "NULL",
"startDate": "2024-09-01T00:00:00.000000",
"finalDate": "2026-01-31T00:00:00.000000",
"EXTERNAL_CONTACTS": {
"count": 0,
"EXTERNAL_CONTACT": []
}
},
"billingItems": [{
"id": "123456",
"productName": "<Product name1>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"refId": "<Billing item refid text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"vatValue": 21.0,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"billingStatus": "ToBeInvoiced",
"productExternalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}]
}, {
"id": "123457",
"productName": "<Product name2>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"refId": "<Billing item refid text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"vatValue": 21.0,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"billingStatus": "ToBeInvoiced",
"productExternalId": [{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<sytem2>",
"id": "<Product old id>"
}]
}],
"servicedItems": [
{
"productName": "<Product name1>",
"productRefid": "<Product code>",
"name": "<Billing item text>",
"refId": "<Billing item refid text>",
"description": "<Billing item description>",
"quantity": 1.0000,
"unitPrice": 1000.00,
"vatValue": 21.0,
"currency": "<EUR, CZK, ...>",
"billingDate": "<2022-09-14T10:00>",
"productExternalId": [
{
"system": "<system1>",
"id": "<Product old id>"
}, {
"system": "<system2>",
"id": "<Product old id>"
}
]
}
]
}Tracking code
Request
POST https://<HOST>/crab/crawler/tracking_code?instance=<instance_name>
{
"code": "ABC",
"userName": "<-- username@workspace -->",
"trackingCodeTypeName": "<-- Dealer -->",
"contactFolder": {
"id": "<Folder id>",
"name": "<Folder name>",
"refId": "<Folder REF ID>",
"category": "anyFolderCategory",
"contact": {
"person": {
"firstName": "<name>",
"lastName": "<surname>"
},
"company": {
"companyName": "<company name>"
},
"externalId": [{
"system": "<system1>",
"id": "<Contact old id>"
}, {
"system": "<sytem2>",
"id": "<Contact old id>"
}]
}
}
}Internal process
The service calls service for creating tracking code.
The aim is to file new trackingCode with type "Dealer" or "Partner" with rerefence to folderId having contact's externalId previously entered by contact service.
Sales Order and Invoice Received
Get Sales Order
Request
GET https://<HOST>/crab/crawler/order-received?instance=<instance_name>&id=<order-received_id>
Response
{
"created": "2024-04-26T00:00:00",
"createdBy": 131841101,
"createdByName": "admin@cime",
"externalNumber": null,
"externalReferenceNumber": null,
"id": 133683101,
"internalDescription": null,
"invoiceNumber": "232410001",
"issuedDate": "2024-04-26",
"journal": "132877101",
"journalName": "Sales Order",
"journalTreeHandle": null,
"modified": "2024-04-26T00:00:00",
"modifiedBy": 131841101,
"modifiedByName": "admin@cime",
"state": 132606101,
"stateName": "Schv\u00e1leno",
"taxationDate": "2024-04-26",
"treeHandle": 131252101,
"dateTransaction": "26.04.2024",
"customId": null,
"supplier": {
"provider": 132419101,
"providerCity": null,
"providerCountry": null,
"providerName": "CIME, s.r.o.",
"providerRegion": null,
"providerStreet": null,
"providerZIP": null,
"userId": 131841101,
"userName": "admin@cime",
"providerExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
]
},
"customer": {
"customer": 133349101,
"customerCity": null,
"customerContact": 133634101,
"customerContactName": "Nov\u00e1k Jind\u0159ich",
"customerCountry": null,
"customerName": "AGRO s.r.o.",
"customerRegId": "0",
"customerRegion": null,
"customerStreet": null,
"customerVATId": "0",
"customerZIP": null,
"customerExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"contactExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
]
},
"shipTo": {
"shipTo": null,
"shipToCity": null,
"shipToCountry": null,
"shipToCustomer": true,
"shipToName": null,
"shipToRegion": null,
"shipToStreet": null,
"shipToZIP": null,
"shipToExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
]
},
"rows": [
{
"account": 132855101,
"accountCode": "602000",
"accountName": "Sales",
"created": "2024-04-26T00:00:00",
"createdBy": 131841101,
"createdByName": "admin@cime",
"customId": null,
"transactionDate": "26.04.2024",
"description": "Nejv\u00edc vychytan\u00fd popis \nk traktoru Lindner Geotrac.",
"childKey": null,
"id": 133685101,
"modified": "2024-04-26T00:00:00",
"modifiedBy": 131841101,
"modifiedByName": "admin@cime",
"parent": null,
"parentId": null,
"parentKey": null,
"recordId": null,
"treeHandle": 131244101,
"userId": 131841101,
"userName": "admin@cime",
"voucher": null,
"orderIndex": 0,
"value": {
"netTotal": 650000,
"currency": "CZK",
"unitPrice": 650000,
"unitQuantity": 1,
"VAT": "DPH 21%",
"VATPercent": 21,
"VATValue": 136500
},
"product": {
"catalogPrice": 800000,
"item": 133445101,
"itemName": "Lindner Geotrac",
"itemcat": null,
"itemcat_name": null,
"itemDescription": "1. Lindner Geotrac",
"itemSerial": null,
"productExternalId": [
{
"system": "<system1>",
"id": "<ABCD-EFGH-ijkl-...>"
},
{
"system": "<sytem2>",
"id": "<ABCD-EFGH-ijkl-...>"
}
]
},
"attributes": {
"attrib0": null,
"attrib0_id": null,
"attrib1": null,
"attrib1_id": null,
"attrib2": null,
"attrib2_id": null,
"attrib3": null,
"attrib3_id": null,
"attrib4": null,
"attrib4_id": null,
"attrib5": null,
"attrib5_id": null,
"attrib6": null,
"attrib6_id": null,
"attrib7": null,
"attrib7_id": null,
"attrib8": null,
"attrib8_id": null,
"attrib9": null,
"attrib9_id": null
},
"context": {
"folder": 133349101,
"folderName": "AGRO s.r.o.",
"folderContactExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"project": 133621101,
"projectName": "Prodej Merlo Turbofarmer",
"projectExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"activity": null,
"activityExternalId": [] # NOT SUPPORTED
},
"trackingCategories": {
"dimension1": null,
"dimension1Name": null,
"dimension2": null,
"dimension2Name": null,
"dimension3": null,
"dimension3Name": null
},
"SHARES": [
{
"id": 133708101,
"recordId": null,
"share": null,
"userId": 131841101,
"userName": "admin@cime",
"folder": 133349101,
"folderContactExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"project": 133621101,
"projectExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"activity": null,
"activityExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"isRemaining": 1,
"units": 1,
"shareUnits": 0,
"percentage": 100,
"total": 650000,
"dimension1": null,
"dimension2": null,
"dimension3": null,
"dimension1Name": null,
"dimension2Name": null,
"dimension3Name": null
}
]
}
],
"totals": {
"currency": "CZK",
"currencyRate": 1,
"total": 786500,
"totalWithVAT": 786500
},
"payment": {
"bankAccount": null,
"bankCode": null,
"bankIBAN": null,
"bankBic": null,
"bankNoteDomestic": null,
"bankNoteForeign": null,
"constantSymbol": null,
"dueDate": "10.05.2024",
"overdue": null,
"paidSync": 0,
"paidManual": 0,
"paymentMethod": null,
"paymentMethodName": null,
"paymentReference": null,
"paymentStatus": 8,
"toBePaid": 786500,
"toBePaidDate": "01.01.1",
"valueRestraint": null,
"valueAuthorized": null
},
"customFields": {
"field0": null,
"field0Id": null,
"field0Txt": null,
"field1": null,
"field1Id": null,
"field1Txt": null,
"field2": null,
"field2Id": null,
"field2Txt": null,
"field3": null,
"field3Id": null,
"field3Txt": null,
"field4": null,
"field4Id": null,
"field4Txt": null,
"field5": null,
"field5Id": null,
"field5Txt": null,
"field6": null,
"field6Id": null,
"field6Txt": null,
"field7": null,
"field7Id": null,
"field7Txt": null,
"field8": null,
"field8Id": null,
"field8Txt": null,
"field9": null,
"field9Id": null,
"field9Txt": null
},
"context": {
"folder": 133349101,
"folderName": "AGRO s.r.o.",
"folderRefId": "UF1",
"folderContactExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"project": 133621101,
"projectName": "Prodej Merlo Turbofarmer",
"projectRefId": null,
"projectExternalId": [
{
"system": "<system1>",
"id": "<Contact old id>"
},
{
"system": "<system2>",
"id": "<Contact old id>"
}
],
"activity": null,
"activityName": null,
"activityRefId": null,
"activityExternalId": [] # NOT SUPPORTED
},
"documents": [],
"texts": {
"description": null,
"headerText": null,
"footerText": null,
"summaryText": null,
"periodFrom": "2024-04-26",
"periodTo": null
},
"trackingCategories": {
"dimension1": null,
"dimension1Name": null,
"dimension2": null,
"dimension2Name": null,
"dimension3": null,
"dimension3Name": null
}
}Create Invoice
Request
// Structure is the same as Sales Order example above
POST https://<HOST>/crab/crawler/invoice-issued?instance=<instance_name>
Update Invoice
Request
// Structure is the same as Sales Order example above
PUT https://<HOST>/crab/crawler/invoice-issued?instance=<instance_name>&id=<invoice_id>
List Invoice Status
Service for listing invoice states.
Request
GET https://<HOST>/crab/crawler/invoice_status?instance=<instance_name>
Success Response
[
{
"stateId": "89342000",
"name": "Issued",
"priority": 99,
"enabled": 3,
"acl": "INVS000000002410",
"treeHandle": "60430000"
},
{
"stateId": "89342001",
"name": "Pending",
"priority": 50,
"enabled": 12,
"acl": "INVS000000002411",
"treeHandle": "60430001"
},
{
"stateId": "89342002",
"name": "Paid",
"priority": 10,
"enabled": 1,
"acl": "INVS000000002412",
"treeHandle": "60430002"
}
]Error Response
{
"result": "FAIL",
"message": "<error message>"
}Timeline
Listing timeline data
Request
GET /timelineSample
GET /api/timeline?contextId=59759502000&contextType=folder&moduleName=WEB&limit=20Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
contextId |
string | No | ID of the context (folderId, projectId, etc.) |
contextType |
string | No | Type of context: folder, project, activity, contact, etc. |
objectType |
string | No | Filter by object name (e.g. MAIL-OPEN, MASSMAIL, FOLDER) |
moduleName |
string | No | Filter by module (e.g. WEB, MESSAGING) |
changeType |
string | No | Filter by change type (CREATED, UPDATED, DELETED) |
createdBy |
string | No | Filter by user ID |
contactId |
string | No | Filter by related contact ID |
fromDate |
datetime | No | Filter changes created after this date |
toDate |
datetime | No | Filter changes created before this date |
limit |
int | No | Max number of results (default: 30) |
offset |
int | No | Pagination offset |
order |
string | No | Order by field (created by default) |
desc |
bool | No | Descending order (default: true) |
Response
{
"total": 4,
"limit": 20,
"offset": 0,
"changes": [
{
"id": "125453031000",
"created": "2025-07-01T17:43:45.47226",
"createdBy": {
"id": "105704465000",
"name": "Robot Atollon"
},
"module": "WEB",
"object": "MAIL-OPEN",
"changeType": "CREATED",
"description": "Message 'AI a budoucnost CRM' opened 1x",
"objectId": "125453030000",
"context": {
"id": "59759502000",
"type": "folder",
"name": "2HHOLINGER s.r.o."
},
"contactId": "59759494000",
"items": [
{
"name": "numberOfVisits",
"valueNew": "1"
}
]
}
]
}
Call Task
Create or update call task for contact folder (lead)
Request
POST /callTaskRequest Payload Example
{
"userName": "john.doe", // Required: Username of person to assign task to
"contextId": "101280664000", // Required: ID of the folder, project, or activity
"contextType": "folder", // Required: One of: folder, project, activity
"subject": "Contact new lead", // Required: Task title
"description": "This lead has been active on the following topics...", // Required
"avoidDuplicates": true, // Optional: Avoid creating duplicate task (default false)
"priority": "high" // Optional: Increase task priority (-1 is high)
}Behaviour
-
Creates a task of system type
com.atollon.tasks.typeofwork.call. -
Sets task metadata (
userId,contextId,title,description,priority = -1, etc.). -
Optionally checks if a similar task (e.g., same user + subject + context) already exists, and skips or updates instead of duplicating. (update description, priority, dateFrom (now, dateTo +2h))
-
Resolves
userNametouserIdusing Atollon’s identity mapping. -
Sets default task timing to now + 2 hours (unless system-defined elsewhere).
-
Notifies the assigned user if
notify = true.
Response 201
{
"status": "created",
"taskId": "125233377000",
"message": "Call task created successfully for user john.doe"
}Response 200 (if deduplication avoids creating new task)
{
"status": "skipped",
"existingTaskId": "125233377000",
"message": "Similar call task already exists. Skipped creation."
}Error 404: User not found
{
"error": "User 'john.doe' not found"
}Error 400: Bad request
{
"error": "Missing required field: contextId"
}Deduplication Logic (if avoidDuplicates = true)
Checks if a task with:
-
same
userName(or resolved userId) -
same
contextIdandcontextType -
same
subject(optional fuzzy match) -
and not completed
...already exists within last X days (configurable). If so, return existing task.