Pular para o conteúdo principal

Boas práticas

Esta página reúne as melhores práticas para garantir uma integração robusta e eficiente com a API Koncili, evitando erros comuns e otimizando o fluxo de conciliação financeira.

1. Validação antecipada de pedidos​

Antes de enviar os lançamentos de uma conciliação, sempre verifique se os pedidos/itens existem no sistema. Isso evita falhas no processo e garante que apenas transações válidas sejam processadas.

Como validar:

  • Utilize o endpoint GET /order para consultar pedidos/itens antes de enviar o lançamento
  • Confirme que os marketplaceCode e accountId estão corretos
  • Verifique se o status do pedido está dentro dos esperados

2. Garantia de consistência nos Lançamentos​

Ao enviar os lançamentos (releases), eles devem corresponder aos extracts registrados nos itens do pedido original

Regras essenciais:

  1. Mesmos tipos:

    • Se o item do pedido tem SALE o lançamento deve possuir SALE também

  2. Mesmo marketplaceCode:

    • O código do pedido/item deve ser idêntico no lançamento

  3. Envio completo em uma única requisição:

    • Não envie lançamentos parciais. Todos os componentes (SALE, COMISSION, SHIP, etc.) devem ser incluídos de uma vez
Valores dos lançamento

Se o valor enviado nos lançamentos (releases) não corresponder exatamente ao valor pré-registrado no item (extracts) a conciliação será consolidada porém com divergência, o que vai gerará um alerta para análise posterior.

3. Gerenciamento de períodos e lotes​

A conciliação agrupa pedidos/itens em um período definido, e esse agrupamento deve ser consistente.

Boas práticas:

  • Defina períodos claros:
    • periodInitDate e periodEndDate devem cobrir todas as datas dos lançamentos, lembrando que o Koncili não aceita conciliações com períodos concomitantes
  • Confira a quantidade de lançamentos (releasesQtd):
    • Esse valor deve ser exatamente igual ao total de releases que serão enviados
Riscos se ignorado
  • Conciliações rejeitadas por inconsistência no releasesQtd
  • Erro no processo de conciliação

4. Tratamento de erros e retentativas​

Como lidar com erros?

Implemente retentativas inteligentes:

  • Para erros 4xx, aguarde antes de tentar novamente

  • Use um backoff exponencial

  • Registre falhas persistentes:

    • Se um lançamento falhar repetidamente, verifique se as informações existem no Koncili

5. Monitoramento e logs​

Manter registros detalhados ajuda a identificar e corrigir problemas rapidamente.

Recomendações

Registre:

  • Timestamps de envios
  • IDs de conciliações e pedidos/itens
  • Respostas da API (sucessos/erros)

Monitore:

  • Pedidos/itens não conciliados
  • Discrepâncias entre extracts e releases
Importante!

Armazenamento do X-Trace-ID:

Cada uma das requisições na API do Koncili retornará no header um valor único de X-Trace-ID, exceto requisições de autenticação..

Registre e armazene o X-Trace-ID retornado em todas as respostas da API Koncili. Esse identificador único é crucial para:

  • Rastreamento de transações
  • Solução ágil de problemas
  • Auditoria