Skip to main content

Technical information

Tiny API endpoints actually consumed by Koncili in this integration — reference for anyone who will support or review the flow.

Tiny endpoints consumed

Only 3 — implemented in TinyHttpClient, in the koncili_erp module.

POST/realms/tiny/protocol/openid-connect/token

OAuth2 authentication — exchanges the authorization code for the access_token/refresh_token (authorization_code flow), and also refreshes the token (refresh_token flow).

GET/public-api/v3/contas-receber/{id}

Queries a receivable entry in Tiny before/during the write-off.

POST/public-api/v3/contas-receber/{id}/baixar

Actual write-off of the receivable entry in Tiny.

Behavior and technical notes

  • Single 2000ms timeout (connect and connection-request) applied to all Tiny calls — no retry or circuit breaker declared in the module.
  • 400/401 errors on token exchange/refresh become TokenExpiredException/OAuth2Exception (HTTP 422 in Koncili).
  • On the receivable and write-off endpoints, the HTTP client captures the error and returns the original status — the write-off processor decides what to do with 401/rate-limit, retrying the token refresh only once after a 401.
  • The OAuth2 flow is started by Koncili's frontend — there is no direct Tiny callback endpoint in this backend module.
  • The authorization code is single-use.

Koncili endpoints that orchestrate this integration

For context — these belong to Koncili itself, not Tiny (see also "Authentication and credentials").

POST/api/erp/{erpType}/credentials

Creates/saves the ERP credential obtained via OAuth2 (e.g. erpType=TINY).

GET/api/erp/{erpType}/credentials/{id}

Queries the connected credential data.

PUT/api/erp/{erpType}/credentials/{id}

Updates data of the existing credential.

POST/api/erp/{erpType}/credentials/{id}/reauth

Forces a new authorization when access expires.

GET/api/erp/credentials/active

Lists active ERP credentials in Koncili's internal catalog.

POST/api/erp/write-offs/finished/by-reconciliations

Triggers write-off orchestration for finished reconciliations.