Pular para o conteúdo principal

Informações técnicas

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

Endpoints do Tiny consumidos

São só 3 — implementados em TinyHttpClient, no módulo koncili_erp.

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

Autenticação OAuth2 — troca o code de autorização pelo access_token/refresh_token (fluxo authorization_code), e também renova o token (fluxo refresh_token).

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

Consulta um título de conta a receber no Tiny antes/durante a baixa.

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

Baixa efetiva do título (write-off) de conta a receber no Tiny.

Comportamento e observações técnicas

  • Timeout único de 2000ms (connect e connection-request) aplicado a todas as chamadas ao Tiny — sem retry ou circuit breaker declarado no módulo.
  • Erros 400/401 na troca/renovação de token viram TokenExpiredException/OAuth2Exception (HTTP 422 no Koncili).
  • Nos endpoints de conta a receber e baixa, o cliente HTTP captura o erro e devolve o status original — quem decide o que fazer com 401/rate-limit é o processador de baixa, que tenta renovar o token uma única vez após 401.
  • O fluxo OAuth2 é iniciado pelo frontend do Koncili — não há endpoint de callback direto do Tiny neste módulo backend.
  • O code de autorização é de uso único.

Endpoints do Koncili que orquestram essa integração

Para contexto — estes são do próprio Koncili, não do Tiny (ver também "Autenticação e credenciais").

POST/api/erp/{erpType}/credentials

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

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

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.