Skip to main content

Roadmap

Integration Guide - Financial Integration API - Koncili

This guide presents the complete workflow for integrating with the Koncili Financial Integration API. Follow the steps in sequence to correctly implement the integration within your ERP.

Important Information​

  • Rate Limit: 3 requests per minute for the reconciliation API.
  • Pagination: 100 records per request.
  • Execution: The process must be executed daily.
  • Best Practices: Always mark records as read after processing.
  • Monitoring: we monitor API usage; any misuse will result in access being blocked or the adoption of pay-per-access policies.

Integration Workflow​

1. Obtain Access Credentials​

The first step is to obtain the username and password for authentication with the Koncili API. Refer to the Authentication Flow page for more information.

Important

Store your credentials in a secure location and never share them in public repositories.

2. Authentication and Refresh Token​

Perform the connection process with the API and configure the refresh token system to maintain an active session.

Important

To learn more about authentication, access the Authentication documentation for further details.

3. Retrieve Unresolved Reconciliations​

Use the API to fetch reconciliations with "Finalized" and "Analyzed" statuses. For more information, refer to: Retrieve Unresolved Reconciliations

GET/externalapi/orderextract/unresolveds
Note

This API returns 100 records per request and has a rate limit of 3 requests per minute. Plan your calls accordingly.

Important

Respect the rate limit to avoid temporary blocks. We recommend implementing request throttling.

4. Record IDs Tracking​

Extract and store the IDs of the received records for use in the subsequent steps of the process.

5. Mark Settlements as Read​

After saving the records in your ERP, mark them as read in the Koncili API using the batch update. Refer to the Batch update settlements as read in Koncili page for more information.

PUT/externalapi/orderextract/read/batch

Request Body:

request.json
[
  49185461, 123132, 132123, 2123
]
Note

Marking records as read in Koncili after saving them to the ERP is a best practice, as it avoids re-reading them and eliminates the need to develop custom controls to fetch the next 100 records.

  1. Daily Flow Control After reading all the records for the day—specifically when the 'count' variable returns 0—stop the API connection flow.
// Control logic
if (response.count === 0) {
    console.log("All records have been processed");
    // Schedule next execution for the following day
    scheduleNextRun();
} else {
    // Continue processing
    processNextBatch();
}
Important

The workflow must be restarted the next day. Implement an automated scheduler to run this process daily.

7. Resolver Repasses no Koncili​

Initiate the processing within the ERP by clearing the accounts receivable. Once cleared, mark the records as resolved in Koncili using the batch update. Refer to the Batch update settlements as resolved in Koncili page for more information.

PUT/externalapi/orderextract/resolve/batch

Request Body:

request.json
[
  49185461, 123132, 132123,2123
]
Note

This is the final step of the flow. After performing the write-off in the ERP, it is essential to mark the records as resolved in Koncili to maintain synchronization.

Additional API: Consult Reconciled Records

If you need to query records that have already been reconciled (cleared in the ERP), use this API. Refer to the Retrieve reconciled settlements page.

GET/externalapi/orderextract/concilieds

This API returns records that were previously marked as resolved in step 7.