FAQ - Settlement API

1. When are reconciliations available in Financial Integration API?

   Reconciliations are only available after the complete processing of the payment report (PDR) in Koncili. This ensures that the data has already been validated and cross-referenced with the orders.

2. What is reconciling?

   Reconciling is the act of comparing information from the same order across different sources—marketplace, payment file—to ensure consistency.

   However, there are two types of reconciliation that are often confused:

   • Financial reconciliation, which is Koncili's focus.
   • Commercial reconciliation, which is typical for sales, planning, or strategy areas.

   Understanding this difference is essential because the two perspectives generate different expectations—and this is often the cause of confusion among users.

3. What exactly is a financial reconciliation?

   It is the process of comparing the value promised by the marketplace with the value effectively paid out.
   If the marketplace reported it would pay R$ 1,000 but transferred R$ 980, Koncili points out a R$ 20 difference, regardless of the reason.

   📌 The focus is financial and objective: how much came in, how much is missing.

4. What is commercial reconciliation?

   Commercial reconciliation analyzes whether the marketplace fulfilled the agreement regarding rules, fees, and commissions.
   For example: the contract stipulated a 10% commission, but the payout came with 12%.
   The marketplace might be correct according to its internal rules, but commercially there is a strategic divergence.

5. Does Koncili perform commercial reconciliation?

   No.
   Koncili is financial by essence: it shows the accounting and operational truth—what was actually paid.
   Commercial analyses can be performed using this data, but they do not interfere with the reconciliation calculation. The Commission, Campaign, and Pending Dashboards can assist in these analyses.

6. Can I automate the settlement process?

   Yes.
   The ERP can consume the pending reconciliations endpoints (/unresolveds), process the settlements, and send the results via the batch resolution endpoint (/resolve/batch).

   This automation is recommended for sellers with a high volume of orders.

7. Can I perform the settlement based on the total sale value?

   Yes. In this case, the ERP records only the gross value (SALE) in accounts receivable, and expenses (commission, shipping, penalties, etc.) must be posted separately in accounts payable.

8. What is the recommended way to perform settlements?

   Koncili recommends settlement by the net amount received, as this model ensures greater transparency, avoids discrepancies with the marketplace statement, and facilitates accounting audits.

9. What happens if the ERP does not return the settlement status?

   Until the ERP confirms the status (e.g., RESOLVED), Koncili will continue to consider that reconciliation as unresolved. This can lead to rework and inconsistencies.

10. What are the possible statuses for a settlement?

    • PENDING → Settlement not yet processed by the ERP.
    • RESOLVED → Settlement successfully completed in the ERP.
    • DIVERGENT → There was a difference between the expected and recorded values.
    • IGNORED → The record will not be handled by the ERP (specific cases).

11. Can I process multiple settlements at once?

    Yes. The API provides batch action endpoints, allowing you to resolve or mark multiple payouts as read in a single request.

12. How do I know which types of payouts a marketplace can generate?

    Use the endpoint:
    GET /externalapi/releasetype/:channelName
    It returns all transaction types (SALE, COMISSION, SHIP, etc.) configured for that marketplace.

13. Do I need to go through the certification process even if I have in-house development?

    Yes. Both Integration Partners and Sellers with in-house development must go through the certification (homologation) process before accessing the production environment.

14. How do shipping entries (SHIP / RETURN_SHIP) work?

    • SHIP → Can represent either the shipping cost paid by the customer and passed to the seller, or a deducted shipping cost.
    • RETURN_SHIP → Refers to the shipping reversal in cases of return or cancellation.

    👉 The settlement method depends on whether your accounting treats shipping as revenue (when passed through) or an expense (when charged).

15. How should I handle returns (RETURN_SALE / DEVOLUTION)?

    • RETURN_SALE → Corresponds to the total or partial reversal of a previously reconciled sale.
    • DEVOLUTION → Net amount returned to the marketplace (e.g., sale canceled after payout).

    👉 It is important for the ERP to record these values to keep the net balance aligned with the marketplace statement.

16. What are expenses not directly linked to an order (e.g., PENALTY)?

    • PENALTY → Fines applied by the marketplace, usually due to delays or cancellations.
      These expenses are not linked to the normal sale/reversal flow but need to be recorded to reflect the financial reality.

    👉 Ideally, the ERP should have a dedicated ledger account for penalties or marketplace operational expenses.

17. What if the marketplace creates a transaction type that doesn't exist in Koncili yet?

    Koncili constantly updates payout types per channel. If a new type arises, it may appear via the API.
    👉 We recommend that the ERP be prepared to handle new types dynamically, always using the /releasetype/:channelName endpoint as an updated reference.

18. How does settlement work for installment sales with early payout (anticipation)?

    In some marketplaces, the customer pays in installments (e.g., 10x), but the payout to the seller is made upfront, as if it were a cash sale.

    In these cases:

    • The marketplace already deducts the financial anticipation fees at the time of payout.
    • The seller receives the net value in a single installment, even though the customer continues to pay the marketplace over time.
    • In the ERP, the settlement should reflect the amount effectively received, rather than the customer's original installment flow.

    👉 How to record in the ERP:

    • Model 1 - Total Sale: Record the gross amount as revenue and account for the anticipation fee as a financial expense.
    • Model 2 - Net Amount Received (Recommended): Record only the net amount after the fee deduction, ensuring accounts receivable reflects the actual cash inflow.

19. What happens to accounts receivable when a sale is canceled after the invoice (NF) is issued?

    When a sale is canceled after the invoice is issued, the seller may have already posted the value in accounts receivable. In this scenario, the accounting must be adjusted:

    • In Koncili: The cancellation appears as a RETURN_SALE or DEVOLUTION entry, depending on the channel, reducing the expected net balance.
    • In the ERP - Recommended treatment:
      • Clear the original entry in accounts receivable.
      • Generate the corresponding reversal/cancellation so the revenue does not remain open.
      • Record the return invoice (if applicable) to ensure the tax effect is also adjusted.

    ⚠️ Point of attention: Do not leave "open" entries in accounts receivable that will never be liquidated. This distorts cash flow and the P&L (DRE).

20. What to do if the value paid by the marketplace differs from the ERP record (e.g., rounding in installments)?

    In installment sales, minor rounding differences are common between the ERP record and the marketplace payout.

    🔹 How Koncili handles it: Koncili captures the value exactly as reported by the marketplace. Therefore, the reconciled value may show minimal differences (cents) compared to the ERP order.

    🔹 How the ERP should handle it:

    • Cents Tolerance: If the difference is small (e.g., up to R$ 0.05 per order), the ERP can accept the marketplace value as valid, posting the difference to a Rounding Differences or Financial Adjustments account.
    • Partial Reversal: If the difference is significant, mark the reconciliation as DIVERGENT for manual handling.

21. Why do I receive the response {"response": "NO_TOKEN", "operation": "NOOP"}?

    This indicates the authentication token (gumgaToken) has expired or was not sent correctly in the request header.

    ✅ Solution: Re-authenticate at the POST /public/api/auth/token endpoint to generate a new valid token.

22. Why do I receive a 403 (Forbidden) error even with a valid token?

    This occurs because the request's source IP is not authorized for the token used.

    ✅ Solution:

    1. Check authorized IPs: GET /externalapi/ip-segmentation
    2. Authorize your current IP: POST /externalapi/ip-segmentation

    {
      "ip": "YOUR.ACCESS.IP"
    }