API functionality and methods : Aico

API functionality and methods

Modified on Tue, 4 Mar at 9:19 AM

The staging API allows the caller to

Get list of available clients configured in the Aico system
Get list of available companies configured in the Aico system
Get list of document templates for a specific client. For each document template, it returns a list of which staging API header and row fields are available
Get list of batches for a specific client
Get list of documents in a specific batch
Create a new batch for a client
Add document(s) to a batch
Close a batch

The first 5 methods (get list of clients/companies/document templates/batches/documents within a batch) exist for the client developer to get information about the configuration of the Aico system. This helps the developer understand the mapping of the API fields to the Aico document template fields.

The rest of the methods are for storing new staging documents and possibly doing error handling as well. Storing new documents can happen in one of two ways:

Create a new batch and immediately include all the documents and their data in a single call.
Create a batch without documents, add documents one-by-one in a loop, and then close the batch once all documents have been added.
1. Create an empty batch in the Open state
2. In a loop, add all documents that should go into the batch
3. Close the batch, thereby marking it as Closed which will also indicate to Aico that the batch can be processed.

Note: It is okay for the customer to add one staging document per batch which will cause Aico to process the documents individually.

API methods

Verb	Path	Description
GET	/staging/clients	Get list of available clients configured in the Aico system
GET	/staging/companies	Get list of available companies configured in the Aico system
GET	/staging/clients/{clientId}/document-templates	Get list of document templates for a specific client. Document templates list what staging API header and row fields are available
GET	/staging/clients/{clientId}/batches	Get list of batches for a specific client.
GET	/staging/batches/{batchId}/documents	Get list of documents in a specific batch
POST	/staging/clients/{clientId}/batches	Create a new batch for a specific client. If the request is sent without documents then it will simply open the batch and return the batch Id. If the request is sent with documents then the batch is opened, the documents added and then automatically closed.
POST	/staging/documents	Add a document to a specific batch
PATCH	/staging/batches/{batchId}/close	Close a specific batch changing it from Open to Closed status

Examples

Get list of clients

This call inspects available clients so that the caller can select the correct one for next calls.

Request URL: https://localhost:7060/staging/clients
Curl: curl -X 'GET' \
'https://localhost:7060/staging/clients' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {token}'

Response headers:
cache-control: no-store 
content-security-policy: frame-ancestors 'none' 
content-type: application/json; charset=utf-8 
date: Mon,28 Oct 2024 08:14:24 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff 
Response code: 200
Response body:
[
 {
   "id": 1,
   "name": "Shared Client 1",
   "contactPersonEMails": null,
   "active": true,
   "invalidDocumentsAllowed": true,
   "retryAllowed": true,
   "defaultCompanyCode": null,
   "defaultDocumentTemplateCode": "StagingDT1"
 },
 {
   "id": 2,
   "name": "Shared Client 2",
   "contactPersonEMails": null,
   "active": true,
   "invalidDocumentsAllowed": true,
   "retryAllowed": true,
   "defaultCompanyCode": null,
   "defaultDocumentTemplateCode": "StagingDT1"
 },
 {
   "id": 3,
   "name": "Shared Client 3",
   "contactPersonEMails": null,
   "active": false,
   "invalidDocumentsAllowed": false,
   "retryAllowed": false,
   "defaultCompanyCode": null,
   "defaultDocumentTemplateCode": null
 }
]

Get document templates and field mappings for a client

Here we get a list of staging header and row fields that are in use and which Aico document template fields they map to. Typically this method is called only during design-time by the customer, when the customer needs to implement their own integration code.

Request URL: https://localhost:7060/staging/clients/1/document-templates
Curl: curl -X 'GET' \
 'https://localhost:7060/staging/clients/1/document-templates' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer {token}'

Response headers:
cache-control: no-store 
content-security-policy: frame-ancestors 'none' 
content-type: application/json; charset=utf-8 
date: Mon,28 Oct 2024 08:16:19 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff 
Response code: 200
Response body:
[
 {
   "code": "StagingDT1",
   "name": "Staging 1",
   "description": null,
   "headerFields": [
     {
       "stagingFieldName": "Text01",
       "aicoFieldName": "Test textHeader1",
       "aicoFieldInternalName": "textHeader1"
     },
     {
       "stagingFieldName": "Text01",
       "aicoFieldName": "Test textHeader2",
       "aicoFieldInternalName": "textHeader2"
     }
   ],
   "rowFields": [
     {
       "stagingFieldName": "Text01",
       "aicoFieldName": "Test textColumn2",
       "aicoFieldInternalName": "textColumn2"
     }
   ]
 }
]

Create a new batch for a client without documents

This call creates a new staging batch for a specific client. If no documents are given, then the batch will stay open and separate calls to the API are needed in order to add documents to the batch.

Request JSON body:
{
 "note": "Batch created from a special source",
 "externalId": "123",
 "validateOnly": false
}

Request URL: https://localhost:7060/staging/clients/1/batches
Curl: curl -X 'POST' \
 'https://localhost:7060/staging/clients/1/batches' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '{
 "note": "Batch created from a special source",
 "externalId": "123",
 "validateOnly": false
}'

Response headers:
cache-control: no-store 
content-security-policy: frame-ancestors 'none' 
content-type: application/json; charset=utf-8 
date: Mon,28 Oct 2024 08:20:34 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff 
Response code: 200
Response body: 6

Create documents

This call adds documents to the already existing and Open batch.

Request JSON body:
[
 {
   "batchId": 6,
   "companyCode": "MYCOMPANY",
   "documentTemplateCode": "StagingDT1",
   "externalId": "1234",
   "comments": "Some comments",
   "text01": "My textHeader1 and textHeader2 value",
   "rows": [
     {
       "lineNumber": 0,
       "text01": "My textColumn2 value"
     }
   ]
 }
]
Request URL: https://localhost:7060/staging/documents
Curl: curl -X 'POST' \
 'https://localhost:7060/staging/documents' \
 -H 'accept: */*' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '[
 {
   "batchId": 6,
   "companyCode": "MYCOMPANY",
   "documentTemplateCode": "StagingDT1",
   "externalId": "1234",
   "comments": "Some comments",
   "text01": "My textHeader1 and textHeader2 value",
   "rows": [
     {
       "lineNumber": 0,
       "text01": "My textColumn2 value"
     }
   ]
 }
]'

Response headers:
cache-control: no-store 
content-length: 0 
content-security-policy: frame-ancestors 'none' 
date: Mon,28 Oct 2024 08:28:53 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff
Response code: 200
Response body: empty

Close batch

This call closes the batch that was previously created and Open. This action will put the batch into Closed state and Aico background service will process the batch and create the Aico documents.

Request URL: https://localhost:7060/staging/batches/6/close
Curl: curl -X 'PATCH' \
 'https://localhost:7060/staging/batches/6/close' \
 -H 'accept: */*' \
 -H 'Authorization: Bearer {token}'

Response headers:
cache-control: no-store 
content-length: 0 
content-security-policy: frame-ancestors 'none' 
date: Mon,28 Oct 2024 08:32:19 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff 
Response code: 200
Response body: empty

Create batch including documents in one call

It is possible to create a new batch including one or more documents in a single call. This will also automatically Close the batch, and the document import will automatically start.

Request JSON body:
{
 "note": "Batch created from a special source",
 "externalId": "123",
 "validateOnly": false,
 "documents": [
   {
     "companyCode": "MYCOMPANY",
     "documentTemplateCode": "StagingDT1",
     "externalId": "1234",
     "comments": "Some comments",
     "text01": "My textHeader1 and textHeader2 value",
     "rows": [
       {
         "lineNumber": 0,
         "text01": "My textColumn2 value"
       }
     ]
   }
 ]
}

Request URL: https://localhost:7060/staging/clients/1/batches
Curl: curl -X 'POST' \
 'https://localhost:7060/staging/clients/1/batches' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '{
 "note": "Batch created from a special source",
 "externalId": "123",
 "validateOnly": false,
 "documents": [
   {
     "companyCode": "MYCOMPANY",
     "documentTemplateCode": "StagingDT1",
     "externalId": "1234",
     "comments": "Some comments",
     "text01": "My textHeader1 and textHeader2 value",
     "rows": [
       {
         "lineNumber": 0,
         "text01": "My textColumn2 value"
       }
     ]
   }
 ]
}'

Response headers:
cache-control: no-store 
content-security-policy: frame-ancestors 'none' 
content-type: application/json; charset=utf-8 
date: Mon,28 Oct 2024 08:20:34 GMT 
server: Kestrel 
strict-transport-security: max-age=2592000; includeSubDomains 
x-content-type-options: nosniff 
Response code: 200
Response body: 7