Perguntas Frequentes - API de Integração Financeira

1. Quando as conciliações ficam disponíveis na API para baixa?

   As conciliações ficam disponíveis somente após o processamento completo da planilha de repasse (PDR) no Koncili. Isso garante que os dados já foram validados e cruzados com os pedidos.

2. O que é conciliar?

   Conciliar é o ato de comparar informações de um mesmo pedido em diferentes fontes - marketplace, arquivo de repasse - para garantir que existe coerência.

   Só que existem dois tipos de conciliação que costumam ser confundidos:

   • A conciliação financeira, que é a do Koncili.
   • A conciliação comercial, que é típica de áreas de vendas, planejamento ou estratégia.

   Entender essa diferença é essencial, porque os dois olhares geram expectativas diferentes - e muitas vezes esse é o motivo de confusão entre usuários.

3. O que é exatamente uma conciliação financeira?

   É o processo de comparar o valor prometido pelo marketplace com o valor efetivamente repassado.
   Se o marketplace informou que pagaria R$ 1.000 e repassou R$ 980, o Koncili aponta R$ 20 de diferença, independentemente do motivo.

   📌 O foco é financeiro e objetivo: quanto entrou, quanto ficou faltando.

4. E o que é conciliação comercial?

   A conciliação comercial analisa se o marketplace cumpriu o combinado em termos de regras, taxas e comissões.
   Por exemplo: o contrato previa 10% de comissão, mas o repasse veio com 12%.
   O marketplace pode estar certo pelas suas regras, mas comercialmente há uma divergência estratégica.

5. O Koncili faz conciliação comercial?

   Não.
   O Koncili é financeiro por essência: ele mostra a verdade contábil e operacional - o que foi realmente pago.
   As análises comerciais podem ser feitas a partir desses dados, mas não interferem no cálculo de conciliação. Os Dashboards de Comissão, Campanha, Pendentes, podem ajudar nesta análises.

6. Posso automatizar o processo de baixa?

   Sim.
   O ERP pode consumir os endpoints de conciliações pendentes (/unresolveds), processar as baixas e enviar o resultado via endpoint de resolução em lote (/ resolve/batch).

   Essa automação é recomendada para sellers com alto volume de pedidos.

7. Posso realizar a baixa pelo valor total da venda?

   Sim. Nesse caso, o ERP registra apenas o valor bruto (SALE) no contas a receber, e as despesas (comissão, frete, penalidade etc.) devem ser lançadas separadamente no contas a pagar.

8. Qual é a forma recomendada de realizar as baixas?

   A Koncili recomenda a baixa pelo valor líquido recebido, pois esse modelo garante maior transparência, evita divergências com o extrato do marketplace e facilita auditorias contábeis.

9. O que acontece se o ERP não retornar o status da baixa?

   Enquanto o ERP não confirmar o status (ex.: RESOLVIDO), o Koncili continuará considerando aquela conciliação como não resolvida. Isso pode gerar retrabalho e inconsistências.

10. Quais são os status possíveis em uma baixa?

    • PENDENTE → Baixa ainda não processada pelo ERP
    • RESOLVIDO → Baixa concluída com sucesso no ERP
    • DIVERGENTE → Houve diferença entre o valor esperado e o valor registrado
    • IGNORADO → Registro não será tratado pelo ERP (casos específicos)

11. Posso processar várias baixas de uma vez?

    Sim. A API disponibiliza endpoints de ações em lote, permitindo resolver ou marcar como lidos múltiplos repasses em uma única requisição.

12. Como sei quais tipos de repasses um marketplace pode gerar?

    Use o endpoint:

    GET /externalapi/releasetype/:channelName

    Ele retorna todos os tipos de lançamentos (SALE, COMISSION, SHIP etc.) configurados para o marketplace.

13. Preciso homologar minha integração mesmo se eu for seller com desenvolvimento próprio?

    Sim. Tanto Parceiros Integradores quanto Sellers com desenvolvimento próprio precisam passar pelo processo de homologação antes de acessar o ambiente de produção.

14. Como funciona o lançamento de frete (SHIP / RETURN_SHIP)?

    • SHIP → pode representar tanto o valor do frete pago pelo cliente e repassado ao seller, quanto um custo de frete descontado.
    • RETURN_SHIP → refere-se ao estorno de frete em casos de devolução ou cancelamento.

    👉 A forma de baixa depende se sua contabilidade considera frete como receita (quando repassado) ou despesa (quando cobrado).

15. Como devo tratar devoluções (RETURN_SALE / DEVOLUTION)?

    • RETURN_SALE → corresponde ao estorno total ou parcial de uma venda já conciliada.
    • DEVOLUTION → valor líquido devolvido ao marketplace (ex.: venda cancelada após repasse).

    👉 É importante que o ERP registre esses valores para manter o saldo líquido alinhado ao extrato do marketplace.

16. O que são despesas não vinculadas diretamente ao pedido (ex.: PENALTY)?

    • PENALTY → são multas aplicadas pelo marketplace, geralmente por atraso ou cancelamento.
      Essas despesas não estão vinculadas ao fluxo normal de venda/estorno, mas precisam ser registradas para refletir a realidade financeira.

    👉 O ideal é que o ERP tenha uma conta contábil própria para penalidades ou despesas operacionais de marketplace.

17. E se o marketplace criar um tipo de lançamento que ainda não existe no Koncili?

    O Koncili atualiza constantemente os tipos de repasses por canal. Caso surja um lançamento novo, ele poderá aparecer via API.
    👉 Recomendamos que o ERP seja preparado para tratar novos tipos dinamicamente, usando sempre o endpoint /releasetype/:channelName como referência atualizada.

18. Como funciona a baixa quando a venda foi parcelada, mas o repasse é antecipado pelo marketplace?

    Em alguns marketplaces, o cliente pode comprar em parcelas (ex.: 10x no cartão), mas o repasse ao seller é feito de forma antecipada, como se fosse à vista.

    Nesses casos:

    • O marketplace já desconta as taxas financeiras de antecipação no momento do repasse.
    • O seller recebe o valor líquido em uma única parcela, mesmo que o cliente ainda vá pagar ao marketplace em várias vezes.
    • No ERP, a baixa deve refletir o valor efetivamente recebido, e não o fluxo original do parcelamento do cliente.

    👉 Como registrar no ERP:

    • Modelo 1 - Total da venda:
      • Registrar o valor bruto como receita e contabilizar a taxa de antecipação como despesa financeira.
    • Modelo 2 - Valor líquido recebido (recomendado):
      • Registrar apenas o valor líquido já descontado da taxa, garantindo que o contas a receber reflita o valor real que entrou em caixa.

    📌 Exemplo prático:

    • Venda: R$ 1.000,00 em 10 parcelas
    • Taxa de antecipação: R$ 50,00
    • Repasse ao seller: R$ 950,00 (à vista)

    No ERP:

    • Receita de venda: R$ 1.000,00
    • Despesa financeira (antecipação): R$ 50,00
    • Repasse líquido recebido: R$ 950,00

19. O que acontece com o contas a receber quando uma venda é cancelada após a emissão da nota fiscal?

    Quando uma venda é cancelada depois da emissão da NF, o seller já pode ter lançado o valor no contas a receber. Nesse cenário, é preciso ajustar a contabilização para refletir o cancelamento:

    • No Koncili:
      • O cancelamento aparece como um lançamento do tipo RETURN_SALE ou DEVOLUTION, dependendo do canal.
      • Esse lançamento reduz o saldo líquido esperado.
    • No ERP - Tratamento recomendado:
      • Baixar o título original lançado no contas a receber (o valor da venda).
      • Gerar o estorno/cancelamento correspondente, para que a receita não permaneça em aberto.
      • Registrar a NF de devolução (quando aplicável), garantindo que o efeito fiscal também seja ajustado.

    📌 Exemplo prático:

    • Venda original: R$ 500,00 (nota emitida, título criado em contas a receber).
    • Cancelamento registrado pelo marketplace: RETURN_SALE - R$ 500,00.

    👉 No ERP:

    • Contas a Receber: título de R$ 500,00 baixado.
    • Receita: revertida via estorno/cancelamento.
    • (Se aplicável) NF de devolução registrada.

    ⚠️ Ponto de atenção:
    Cada empresa pode ter política própria para tratar cancelamentos, mas o mais importante é não deixar títulos "em aberto" no contas a receber que nunca serão liquidados. Isso gera distorção no fluxo de caixa e na DRE.

20. O que fazer se o valor repassado pelo marketplace for diferente do registrado no ERP (ex.: vendas parceladas com arredondamento)?

    Em vendas parceladas, é comum que haja pequenas diferenças de arredondamento entre o valor da venda registrado no ERP e o valor efetivamente repassado pelo marketplace.

    📌 Exemplo prático:

    • Valor da venda: R$ 997,37
    • Parcelado em 7x → cada parcela calculada pelo marketplace pode resultar em casas decimais diferentes, ex.: R$ 142,48 por parcela.
    • 7 x 142,48 = R$ 997,36 → diferença de R$ 0,01 em relação ao valor original.

    🔹 Como o Koncili trata

    O Koncili captura o valor exatamente como informado pelo marketplace no repasse.
    Portanto, o valor conciliado pode apresentar diferenças mínimas (centavos) em relação ao pedido registrado no ERP.

    🔹 Como o ERP deve tratar

    O ideal é adotar uma política contábil para lidar com diferenças de arredondamento:

    • Tolerância de centavos
      • Se a diferença for pequena (ex.: até R$ 0,05 por pedido), o ERP pode aceitar o valor repassado pelo marketplace como válido.
      • O ajuste deve ser contabilizado em uma conta de Diferenças de Arredondamento ou Ajustes Financeiros.
    • Estorno parcial (se for divergência maior)
      • Se a diferença for significativa (acima da tolerância definida pela contabilidade), a conciliação deve ser sinalizada como DIVERGENTE.
      • O ERP deve registrar o ajuste e notificar a contabilidade.

    ⚖️ Boas práticas recomendadas

    • Definir política de tolerância no ERP para diferenças de centavos (ex.: até R$ 0,05 ou 0,1% do valor da venda).
    • Mapear uma conta contábil específica para registrar diferenças de arredondamento, mantendo a DRE e o fluxo de caixa consistentes.
    • Auditar regularmente diferenças acumuladas, principalmente em vendas parceladas de alto volume.

    👉 Resumindo:

    • Pequenas diferenças = ajustar automaticamente em conta de arredondamento.
    • Diferenças relevantes = marcar como divergência e tratar manualmente.

21. Por que ao fazer a chamada da API recebo o retorno {"response": "NO_TOKEN", "operation": "NOOP"}?

    Esse retorno indica que o token de autenticação (gumgaToken) expirou ou não foi enviado corretamente no header da requisição.

    📌 Motivo:

    • O gumgaToken tem validade de 30 minutos. Após esse período, ele se torna inválido e a API não autoriza novas chamadas.

    ✅ Como resolver:

    1. Realize novamente a autenticação no endpoint POST /public/api/auth/token para gerar um novo token válido.

    2. Atualize o header das próximas requisições com o novo gumgaToken.

    💡 Recomenda-se que o ERP implemente um mecanismo automático de refresh do token a cada 25-30 minutos para evitar interrupções na comunicação.

22. Por que recebo o erro 403 (Forbidden) mesmo com o token válido?

    Isso ocorre porque o IP de origem da requisição não está habilitado para o token usado.

    📌 Motivo:

    • A API Koncili vincula cada token a uma lista específica de IPs autorizados. Se o seu IP não estiver cadastrado, o acesso será bloqueado.

    ✅ Como resolver:

    1. Verifique os IPs liberados: GET /externalapi/ip-segmentation

    2. Libere o seu IP atual: POST /externalapi/ip-segmentation

    {
      "ip": "SEU.IP.DE.ACESSO"
    }

    3. Remova IPs antigos (opcional): DELETE /externalapi/ip-segmentation

    {
      "ip": "IP.A.REMOVER"
    }

    💡 Após adicionar o IP, aguarde alguns minutos para a propagação da permissão antes de novas chamadas.

    Em casos de IP dinâmico, contate erp@koncili.com