How the export works
How to create and export
To import data into the client app, it must create an export in Candis using the endpoint POST https://api.candis.io/v1/organizations/{organizationId}/exports, which will respond with the following.
Sample Request
curl -X POST
https://api.candis.io/v1/organizations/{organizationId}/exports
-H 'Content-Type: application/json'
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Sample Response
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"postingsCount": 10,
"status": "EXPORTING"
}
The ID is an important piece of information required in all other export-related endpoints. The export creation process in Candis is an asynchronous task and depending on the volume of postings ready to export, it may take a bit of time to generate assets. Therefore, the initial status is set to EXPORTING.
How to check export status
To track the progress of the export, the client application should periodically make aGET https://api.candis.io/v1/organizations/{organizationId}/exports/{exportId} and check the status. Initially, the status will be EXPORTING. Once the export status is marked as EXPORTED, FAILED, or PARTIALLY_EXPORTED, the posting data of the export can be fetched.
Sample Request
curl -X GET
https://api.candis.io/v1/organizations/{organizationId}/exports/{exportId}
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Sample Response
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"postingsCount": 10,
"status": "EXPORTED"
}
How to fetch exporting data (posting)
To retrieve the posting data, the client application should call the endpoint GET https://api.candis.io/v1/organizations/{organizationId}/exports/{exportId}/postings. Before calling this endpoint, ensure to make a GET request to https://api.candis.io/v1/organizations/{organizationId}/exports/{exportId} to verify that the status is not EXPORTING.
The response from this endpoint provides details about the postings, including successful postings and information about any failed postings along with the reason for their failure. Additionally, the response includes a files field containing downloadable URLs for files such as invoice PDFs and audit trails.
Sample Request
curl -X GET \
https://api.candis.io/v1/organizations/{organizationId}/exports/{exportId}/postings \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Sample Response
{
"successfulPostings": [
{
"entityGuid": "123e4567-e89b-12d3-a456-426614174000",
"type": "DOCUMENT",
"status": "EXPORTED",
"amount": {
"value": 100,
"currencyCode": "EUR"
},
"contact": {
"accountsPayableNumber": "7000001"
},
"invoiceId": "1234",
"invoiceDate": "2024-01-01T00:00:00Z",
"files": [
{
"id": "56092830983242",
"url": "https://api.candis.io/v1/organization/org-id/files/1234",
"name": "invoice.pdf",
"type": "INVOICE"
}
],
"url": "https://my.candis.io/alpha-organization/archive/123e4567-e89b-12d3-a456-426614174000",
"documentType": "Incoming Invoice",
"splitPostings": [
{
"note": "Some note",
"amount": 100,
"costCenter": {
"code": "CC-123"
},
"costObject": {
"code": "CC-123"
},
"bookingKey": {
"taxCode": "9"
},
"postingText": "Some text",
"generalLedgerAccount": "8400"
}
]
}
],
"failedPostings": [
{
"id": "1234",
"invoiceId": "1234",
"errorCode": "EXPORTABLE_POSTINGS_NOT_FOUND"
}
]
}
How to Fetch the Export History of the Organization
The endpoint GET https://api.candis.io/v1/organizations/{organizationId}/exports is an additional endpoint that can be useful when the client app needs to sync past exports. This endpoint is paginated, allowing the client to retrieve exports in batches by specifying the offset and limit as query parameters. Below is a sample calculation for the offset to retrieve the next page:
How to calculate the next offset
next_offset = current_offset + limit
Sample Request
curl -X GET \
'https://api.candis.io/v1/organizations/{organizationId}/exports?offset=0&limit=10' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Sample Response
{
"exports": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"postingsCount": 10,
"status": "EXPORTED"
}
{
"id": "123e4567-e89b-12d3-a456-323498723492",
"postingsCount": 10,
"status": "EXPORTED"
}
],
"pagination": {
"pageCount": 1,
"pageSize": 10,
"totalCount": 2
}
}
How to Download Posting Files (Invoice, Audit Trail, and Attachment PDFs)
The file download endpoint is GET https://api.candis.io/v1/organizations/{organizationId}/files/{fileId}, which responds with binary data, and the content type is application/pdf. This URL is already generated in the posting response under the files field. The client application can call this URL with an authentication header.
Sample Request
curl -X GET \
'https://api.candis.io/v1/organizations/{organizationId}/files/{fileId}' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--output downloaded_file.pdf