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

Function progress

Company contact
Person contact

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

Function progress

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=10
Parameters
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

GET https://<HOST>/crab/crawler/project?instance=<instance_name>&externalSystem=<external_system>&externalId=<external_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

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

GET https://<HOST>/crab/crawler/activity?instance=<instance_name>&category=<fpatypecategory>&createdFrom=<created_from>&statusName="Initial"&dimension1Name="Organization Unit A"

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 /timeline
Sample
GET /api/timeline?contextId=59759502000&contextType=folder&moduleName=WEB&limit=20
Request 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)
{
  "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 /callTask
Request 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
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:

...already exists within last X days (configurable). If so, return existing task.


Revision #125
Created 13 September 2022 10:32:17 by Jan Safka
Updated 8 July 2025 12:47:08 by Jan Safka