ERP integration
During custom integration to ERP which is currently not directly supported by Digitoo, it is possible to create custom annotation schema in order to facilitate the needs of ERP system.
Each queue is by default equipped with annotation scheme which you are able to view via API GET queue
User is able to define custom annotation schema following principals here. The creation of custom annotation scheme can be triggered via PUT call to /api/v2/queues/queueId/annotation-schema
Example of adding custom annotation schema:
curl --location --request PUT 'https://api.digitoo.ai/api/v2/queues/:queueId/annotation-schema' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer :authToken' \
--data '{
"annotation_schema": [
{
"type": "separator",
"key": "<string>",
"datatype": "date",
"default_value": [
"<string>",
"<string>"
],
"subfields": [
{
"key": "<string>",
"datatype": "date",
"message": "<string>",
"hidden": false,
"required": ""
},
{
"key": "<string>",
"datatype": "date",
"message": "<string>",
"hidden": false,
"required": ""
}
],
"message": "<string>",
"hidden": false,
"required": "",
"autofill": [
"<string>",
"<string>"
],
"multivalue": false,
"section_message_key": "supplier_details",
"separator_key": "<string>"
},
{
"type": "separator",
"key": "<string>",
"datatype": "numeric",
"default_value": [
"<string>",
"<string>"
],
"subfields": [
{
"key": "<string>",
"datatype": "register",
"message": "<string>",
"hidden": false,
"required": ""
},
{
"key": "<string>",
"datatype": "numeric",
"message": "<string>",
"hidden": false,
"required": ""
}
],
"message": "<string>",
"hidden": false,
"required": "",
"autofill": [
"<string>",
"<string>"
],
"multivalue": false,
"section_message_key": "pohoda_supplier_details",
"separator_key": "<string>"
}
]
}shOnce you have your schema defined, you are able to put register values directly to Digitoo so user is able to choose them during annotating. These registers usually represent tax related values or expense categories. The url to upload register is POST to /api/v2/registers
Example of calling POST registers
curl --location --request POST 'https://api.digitoo.ai/api/v2/registers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer :authToken' \
--data '{
"queue_id": "<string>",
"registers": [
{
"type": "<string>",
"options": [
{
"label": "<string>",
"value": "<string>"
},
{
"label": "<string>",
"value": "<string>"
}
]
},
{
"type": "<string>",
"options": [
{
"label": "<string>",
"value": "<string>"
},
{
"label": "<string>",
"value": "<string>"
}
]
}
],
"method": "replace"
}'shMethods of registers upload
There are currently 3 possible methods to upload new registers defined in the method field of the request.
| Method | Explanation |
|---|---|
| replace | This will upload all registers in the request and delete any previously uploaded registers (only for specified register types). |
| append | This will upload all registers in the request and append these to previously existing registers. |
| upsert | This will upload all registers, updating existing and appending new ones |
After this you are able to start uploading documents to extract data from them.
There are now 2 ways to get documents which are ready to export. The preferred way is via pre-defined webhook on the document. You will received a call for every document's status change. Information about body and request specifics can be found here in the webhook notifications section.
The webhooks are documented here.
Another way is to periodically call our API to fetch documents which are in the ready-to-export status. This can be done for whole organization, whole workspace or for a specific queue by calling any of these:
/api/v2/organizations/:organizationId/documents?filters[status]=ready-to-export/api/v2/workspaces/:workspaceId/documents?filters[status]=ready-to-export/api/v2/queues/:queueId/documents?filters[status]=ready-to-export
Once the processing of document is complemented you are able to change the status either to exported and provide internal ERP ID to Digitoo or to export-errored and provide the error to be shown in Digitoo.
It is recommended to set each of the documents to exporting status in order to avoid duplicate entries in your ERP.
In case you are fetching documents via one of the above APIs and it takes long time to complete and there is a new request to fetch documents in ready-to-export status, it can happen that documents which are already started processing will be processed again. In order to avoid this, you can set each document when you start processing them into exporting status.
Example of status change
curl --location --request PATCH 'https://api.digitoo.ai/api/v2/documents/<uuid>/status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer :authToken' \
--data '{
"status": "export-errored",
"internal_erp_id": "<string>",
"export_error": "<string>"
}'shDocument status flow
Following image represents document status flow form its initial input to the system (either via API, email import or manual import).
Statuses explained
| Status | Enum | Description |
|---|---|---|
| Received | received | Initial status of document after upload. |
| Enqueued for extraction | enqueued-for-extraction | This status is assigned automatically after extraction is initiated |
| Waiting for human approval | waiting-for-human-approval | In case of active approval tab the document will be set for approval |
| Waiting for human validation | waiting-for-human-validation | Once document is extracted by AI it is set to this status |
| Ready to export | ready-to-export | Set this status once document is ready to be exported (eg. by Send button in App) |
| Exporting | exporting | Document is currently being exported |
| Exported | exported | Export is done, document is now visible in ERP |
| Export errored | export-errored | Export has failed, export error message is mandatory to inform user about the error |
| Rejected | rejected | In case of active approval tab, document can be rejected |
| Deleted | deleted | Document is moved to the Deleted folder |
| Postponed | postponed | Document can be postponed and user can return to it at a later date |
| External processing | external-processing | Document can be set to this status which removes it from App UI. It is useful when there are many external validations |
| Extraction errored | extraction-errored | AI engine may fail to extract the document. It is still possible to annotate manually |
| Extraction rejected | extraction-rejected | In case of SPAM settings turned on, AI engine may skip documents which are not invoices. These documents can be forced to extraction |
| Approval restarted | approval-restarted | In case of active advanced approval, the whole approval process can be restarted |
Agent versioning via User-Agent
New version of agent notification
In case you integration relies on a piece of software which is installed for each client, it is recommended to sent user agent header in each API call.
This header represents current version of the software and is able to determine whether there is a newer version for each client and inform them to upgrade in Digitoo App.
curl --location --request [METHOD] '[URL]' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer :authToken' \ --header 'User-Agent: [USER_AGENT]'bash
User agent format
cz.digitoo.agent.[YOUR_AGENT_NAME].[LOCALE]/[VERSION]bash
An example of user-agent header is as follows:
The user-agent header must fulfil the following regex:
^cz\.digitoo\.agent\..*\..*\/(.*)$bash
Digitoo saves version from User-Agent to workspace unit and when there is a new version of agent for ERP type which workspace was created with, workspace unit users are requested to updated.