Pular para o conteúdo principal

Informações técnicas

Endpoints da API do Bling efetivamente consumidos pelo Koncili nesta integração — referência para quem vai dar suporte ou revisar o fluxo.

Endpoints do Bling consumidos

São 7 — implementados em BlingHttpClient, no módulo koncili_erp. API Bling v3 (/Api/v3): autenticação em www.bling.com.br, API em api.bling.com.br. Não há sandbox — o host é sempre produção.

POST/Api/v3/oauth/token

Autenticação OAuth2 — troca o authorization_code pelo access_token/refresh_token e também renova o token (grant_type=refresh_token). Autenticação via Authorization: Basic base64(client_id:client_secret), corpo form-urlencoded.

GET/Api/v3/contas/receber

Job diário — lista os títulos em aberto (o "driver" da sincronização), paginado, 1 dia por consulta (situacoes[]=1&tipoFiltroData=E).

GET/Api/v3/nfe/{id}

Resolve o número do pedido a partir da Nota Fiscal — rota real de vínculo (a maioria dos títulos vem de nota fiscal, não de venda direta).

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

Resolve o número do pedido a partir do id da venda, quando o título vem direto de uma venda.

GET/Api/v3/pedidos/vendas

Busca vendas em lote por número de pedido (numerosLojas[]=...) — usado na resolução "na hora" (rede de segurança) quando o job ainda não vinculou.

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

Verifica o título antes de baixar — checagem de divergência de valor.

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

Executa a baixa (payload com data, forma de pagamento, portador, categoria, histórico e valores).

Comportamento e observações técnicas

  • O token de acesso dura ~6 horas e o refresh_token ~30 dias; a janela do refresh desliza a cada renovação bem-sucedida.
  • Erros 400/401 na troca/renovação de token tornam a credencial inválida — não existe estado "expirado" separado; é preciso reconectar.
  • O rate limit (3 req/s, 120.000/dia) é controlado pelo próprio Koncili — o Bling não expõe headers de rate limit. Ao estourar, o item espera e é reenfileirado.
  • O fluxo OAuth2 é iniciado pelo frontend do Koncili; não há endpoint de callback direto do Bling neste módulo backend.

Endpoints do Koncili que orquestram essa integração

Para contexto — estes são do próprio Koncili, não do Bling (ver também "Autenticação e credenciais"). São os mesmos endpoints genéricos por ERP, com erpType=BLING.

POST/api/erp/{erpType}/credentials

Cria/salva a credencial ERP obtida via OAuth2 (ex.: erpType=BLING).

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

Consulta os dados da credencial conectada.

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

Atualiza dados da credencial existente.

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

Força uma nova autorização quando o acesso fica inválido.

GET/api/erp/credentials/active

Lista credenciais ERP ativas no catálogo interno do Koncili.

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

Dispara orquestração de baixa para conciliações finalizadas.