Skip to main content

Technical information

Bling API endpoints actually consumed by Koncili in this integration — a reference for whoever supports or reviews the flow.

Bling endpoints consumed

There are 7 — implemented in BlingHttpClient, in the koncili_erp module. Bling API v3 (/Api/v3): authentication at www.bling.com.br, API at api.bling.com.br. There is no sandbox — the host is always production.

POST/Api/v3/oauth/token

OAuth2 authentication — exchanges the authorization_code for the access_token/refresh_token and also renews the token (grant_type=refresh_token). Authentication via Authorization: Basic base64(client_id:client_secret), form-urlencoded body.

GET/Api/v3/contas/receber

Daily job — lists open receivables (the sync "driver"), paginated, 1 day per query (situacoes[]=1&tipoFiltroData=E).

GET/Api/v3/nfe/{id}

Resolves the order number from the Invoice (NF-e) — the real linking route (most receivables come from an invoice, not a direct sale).

GET/Api/v3/pedidos/vendas/{id}

Resolves the order number from the sale id, when the receivable comes straight from a sale.

GET/Api/v3/pedidos/vendas

Fetches sales in batch by order number (numerosLojas[]=...) — used in the on-the-spot resolution (safety net) when the job has not linked yet.

GET/Api/v3/contas/receber/{id}

Checks the receivable before writing off — value divergence check.

POST/Api/v3/contas/receber/{id}/baixar

Executes the write-off (payload with date, payment method, holder, category, history and values).

Behavior and technical notes

  • The access token lasts ~6 hours and the refresh_token ~30 days; the refresh window slides on every successful renewal.
  • 400/401 errors on token exchange/renewal make the credential invalid — there is no separate "expired" state; a reconnection is required.
  • The rate limit (3 req/s, 120,000/day) is controlled by Koncili itself — Bling does not expose rate-limit headers. On overflow, the item waits and is re-queued.
  • The OAuth2 flow is started by Koncili's frontend; there is no direct Bling callback endpoint in this backend module.

Koncili endpoints that orchestrate this integration

For context — these belong to Koncili, not Bling (see also "Authentication and credentials"). They are the same generic per-ERP endpoints, with erpType=BLING.

POST/api/erp/{erpType}/credentials

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

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

Reads 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 the access becomes invalid.

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.