Saltar al contenido principal

Información técnica

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

Endpoints de Olist/Tiny consumidos

Son solo 3 — implementados en TinyHttpClient, en el módulo koncili_erp.

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

Autenticación OAuth2 — intercambia el code de autorización por el access_token/refresh_token (flujo authorization_code), y también renueva el token (flujo refresh_token).

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

Consulta un documento por cobrar en Olist/Tiny antes/durante la aplicación del cobro.

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

Aplicación efectiva del cobro (write-off) del documento por cobrar en Olist/Tiny.

Comportamiento y observaciones técnicas

  • Timeout único de 2000ms (connect y connection-request) aplicado a todas las llamadas a Olist/Tiny — sin retry ni circuit breaker declarado en el módulo.
  • Los errores 400/401 en el intercambio/renovación del token se convierten en TokenExpiredException/OAuth2Exception (HTTP 422 en Koncili).
  • En los endpoints de cuenta por cobrar y de aplicación del cobro, el cliente HTTP captura el error y devuelve el estado original — quien decide qué hacer con 401/rate-limit es el procesador de aplicación del cobro, que intenta renovar el token una única vez después de un 401.
  • El flujo OAuth2 lo inicia el frontend de Koncili — no hay endpoint de callback directo de Olist/Tiny en este módulo backend.
  • El code de autorización es de un solo uso.

Endpoints de Koncili que orquestan esta integración

Como contexto — estos son del propio Koncili, no de Olist/Tiny (ver también "Autenticación y credenciales").

POST/api/erp/{erpType}/credentials

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

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 expira.

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.