Skip to main content

Best Practices

This page provides the best practices to ensure an efficient integration with the Koncili API, preventing common errors and optimizing the financial reconciliation workflow.

1. Early Order Validation​

Before submitting reconciliation releases, always verify that the orders/items exist within the system. This prevents process failures and ensures that only valid transactions are processed.

How to validate:

  • Use the GET /order endpoint to query orders/items before submitting a financial entry.
  • Confirm that the marketplaceCode and accountId are correct.
  • Verify that the order status is among those expected by the system.

2. Ensuring Consistency in Entries​

When submitting entries (releases), they must correspond to the extracts registered in the original order items.

Essential Rules:

  1. Matching Types:

    • If the order item contains a SALE type, the entry must also contain a SALE type.

  2. Matching marketplaceCode:

    • The order/item code must be identical in the entry submission.

  3. Complete Submission in a Single Request:

    • Do not submit partial entries. All components (SALE, COMISSION, SHIP, etc.) must be included at once.
Entry Values

If the value submitted in the entries (releases) does not exactly match the pre-registered value in the item (extracts), the reconciliation will be consolidated but marked with a discrepancy, triggering an alert for subsequent analysis.

3. Period and Batch Management​

Reconciliation groups orders/items within a defined period, and this grouping must remain consistent. Boas práticas:

  • Define clear periods:
    • periodInitDate and periodEndDate must cover all entry dates. Note that Koncili does not accept reconciliations with overlapping periods.
  • Verify the entry count (releasesQtd):
    • This value must exactly match the total number of releases that will be submitted.
Risks if ignored
  • Reconciliations rejected due to inconsistency in releasesQtd.
  • Errors in the reconciliation process.

4. Error Handling and Retries​

How to handle errors?

Implement intelligent retry policies:

  • For 4xx errors, investigate the request payload before attempting a retry.
  • Use exponential backoff for transient failures.
  • Log persistent failures:
    • If a submission fails repeatedly, verify if the corresponding information already exists in Koncili.

5. Monitoring and Logs​

Maintaining detailed logs is essential to identify and resolve issues quickly.

Recommendations

Log the following:

  • Submission timestamps
  • Reconciliation and order/item IDs
  • API responses (successes and errors)

Monitor the following:

  • Unreconciled orders and items
  • Discrepancies between extracts and releases
Important!

Storing the X-Trace-ID:

Every request to the Koncili API will return a unique X-Trace-ID in the header, with the exception of authentication requests.

Log and store the X-Trace-ID returned in all Koncili API responses. This unique identifier is crucial for:

  • Transaction tracking
  • Rapid troubleshooting
  • Auditing