Saltar al contenido principal

Información técnica

Endpoints de la API de Bling que Koncili consume efectivamente en esta integración — referencia para quien vaya a dar soporte o revisar el flujo.

Endpoints de Bling consumidos

Son 7 — implementados en BlingHttpClient, en el módulo koncili_erp. API Bling v3 (/Api/v3): autenticación en www.bling.com.br, API en api.bling.com.br. No hay sandbox — el host siempre es producción.

POST/Api/v3/oauth/token

Autenticación OAuth2 — intercambia el authorization_code por el access_token/refresh_token y también renueva el token (grant_type=refresh_token). Autenticación mediante Authorization: Basic base64(client_id:client_secret), cuerpo form-urlencoded.

GET/Api/v3/contas/receber

Job diario — lista los documentos por cobrar abiertos (el "driver" de la sincronización), paginado, 1 día por consulta (situacoes[]=1&tipoFiltroData=E).

GET/Api/v3/nfe/{id}

Resuelve el número del pedido a partir de la nota fiscal — ruta real de vínculo (la mayoría de los documentos por cobrar viene de una nota fiscal, no de una venta directa).

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

Resuelve el número del pedido a partir del id de la venta, cuando el documento por cobrar viene directamente de una venta.

GET/Api/v3/pedidos/vendas

Busca ventas por lotes por número de pedido (numerosLojas[]=...) — se usa en la resolución "en el momento" (red de seguridad) cuando el job todavía no hizo el vínculo.

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

Verifica el documento por cobrar antes de aplicar el cobro — comprobación de divergencia de monto.

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

Ejecuta la aplicación del cobro (payload con fecha, forma de pago, portador, categoría, historial y montos).

Comportamiento y observaciones técnicas

  • El token de acceso dura ~6 horas y el refresh_token ~30 días; la ventana del refresh se desplaza con cada renovación exitosa.
  • Los errores 400/401 en el intercambio/renovación del token vuelven la credencial inválida — no existe un estado "expirado" separado; es necesario reconectar.
  • El rate limit (3 req/s, 120.000/día) lo controla el propio Koncili — Bling no expone headers de rate limit. Al superarlo, el ítem espera y vuelve a la cola.
  • El flujo OAuth2 lo inicia el frontend de Koncili; no hay endpoint de callback directo de Bling en este módulo backend.

Endpoints de Koncili que orquestan esta integración

Como contexto — estos son del propio Koncili, no de Bling (ver también "Autenticación y credenciales"). Son los mismos endpoints genéricos por ERP, con erpType=BLING.

POST/api/erp/{erpType}/credentials

Crea/guarda la credencial ERP obtenida vía OAuth2 (p. ej.: erpType=BLING).

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

Consulta los datos de la credencial conectada.

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

Actualiza los datos de la credencial existente.

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

Fuerza una nueva autorización cuando el acceso queda inválido.

GET/api/erp/credentials/active

Lista las credenciales ERP activas en el catálogo interno de Koncili.

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

Dispara la orquestación de la aplicación del cobro para conciliaciones finalizadas.