Pular para o conteúdo principal

Roadmap

Guia de Integração - API de Integração Financeira - Koncili

Este guia apresenta o fluxo completo para integração com a API de Integração Financeiro do Koncili. Siga os passos na sequência para implementar corretamente a integração no seu ERP

Informações Importantes​

  • Rate Limit: 3 requisições por minuto na API de conciliações.
  • Paginação: 100 registros por requisição.
  • Execução: Processo deve ser executado diariamente.
  • Boas Práticas: Sempre marque registros como lidos após processar.
  • Monitoramento: Monitoramos o uso da API e se houver uso indevido o acesso será bloqueado ou adotaremos políticas de cobrança por acesso.

Fluxo de Integração​

1. Obter Credenciais de Acesso​

Primeiro passo é obter o usuário e senha para autenticação na API do Koncili. Consulte a página Fluxo de autenticação para mais informações.

Importante

Guarde suas credenciais em um local seguro e nunca as compartilhe em repositórios públicos.

2. Autenticação e Refresh Token​

Realize o processo de conexão com a API e configure o sistema de refresh token para manter a sessão ativa.

Importante

Para saber mais sobre autenticação, acesse a documentação Autenticação para mais informações.

3. Obter Conciliações Não Resolvidas​

Utilize a API para buscar as conciliações Finalizadas e Analisadas. Consulte para mais informações: Obtém conciliações não resolvidas

GET/externalapi/orderextract/unresolveds
Observação

Esta API devolve 100 registros por requisição e tem um rate limit de 3 requisições por minuto. Planeje suas chamadas adequadamente.

Importante

Respeite o rate limit para evitar bloqueios temporários. Recomendamos implementar um controle de requisições.

4. Anotar IDs dos Registros​

Extraia e armazene os IDs dos registros recebidos para uso nas próximas etapas do processo.

5. Marcar Repasses como Lidos​

Após salvar os registros no seu ERP, marque-os como lidos na API do Koncili em lote. Consulte a página Atualiza repasses no Koncili como lido em lote para mais informações.

PUT/externalapi/orderextract/read/batch

Request Body:

request.json
[
  49185461, 123132, 132123,2123
]
Observação

Após salvar os registros no ERP, marcar eles no Koncili como lidos é uma boa prática, pois evita ler novamente, além de não precisar desenvolver controles para ler os 100 registros seguintes.

6. Controle de Fluxo Diário​

Após ler todos os registros do dia, ou seja, quando a variável 'count' retornar 0, pare o fluxo de conexão com a API.

// Lógica de controle
if (response.count === 0) {
    console.log("Todos os registros foram processados");
    // Agendar próxima execução para o dia seguinte
    scheduleNextRun();
} else {
    // Continuar processamento
    processNextBatch();
}
Importante

O fluxo deve ser reiniciado no dia seguinte. Implemente um agendamento automático para executar esse processo diariamente.

7. Resolver Repasses no Koncili​

Inicie o processamento no ERP baixando as contas a receber. Após baixá-las, marque os registros como resolvidos no Koncili em lote. Consulte a página Atualiza repasses no Koncili como lido em lote para mais informações.

PUT/externalapi/orderextract/resolve/batch

Request Body:

request.json
[
  49185461, 123132, 132123,2123
]
Observação

Este é o passo final do fluxo. Após a baixa das contas no ERP, é essencial marcar os registros como resolvidos no Koncili para manter a sincronização.

API Adicional: Consultar Registros Conciliados

Caso precise consultar os registros já conciliados (baixados no ERP), utilize esta API . Consulte a página Obtém conciliações resolvidas

GET/externalapi/orderextract/concilieds

Esta API retorna os registros que já foram marcados como resolvidos no passo 7.