Fluxo Geral do Koncili

Esse fluxo define o comportamento geral para uma aplicação integradora à nossa API. Os pedidos poderão ser enviados ao Koncili, o qual será responsável por identificar, em uma conciliação, quais repasses o marketplace está realizando corretamente e, após a conciliação ser finalizada é possível recuperar os repasses referentes ao pedido e realizar a baixa das contas a receber no sistema integrador.


Descrição do fluxo:

Personagens:

  • Aplicação integrador: qualquer aplicação que faça integração com o Koncili. Por exemplo um Hub, e-commerce ou um ERP.
  • Koncili: todas as aplicações que fazem parte do Koncili.
  • Seller: cliente que contratou os serviços do Koncili.
  • Marketplace: canal de venda responsável por realizar os repasses (Exemplo: B2W, NETSHOES, Mercado Livre entre outros).

Ações:

  • Envia pedidos: operação POST que o Koncili recebe para adicionar pedidos para serem conciliados posteriormente.
  • Busca Repasses: usuário baixa a planilha com todos os repasses feitos pelo Marketplace em um período.
  • Envia Repasses: upload da planilha de repasses para conciliação dos pedidos.
  • Inicializa conciliação: inicia o processo de conciliação em um determinado período.
  • Exibe resultados: informações resultantes do processo de conciliação.
  • Resolve divergências: resolução pelo usuário dos repasses incorretos.
  • Finaliza conciliação: marca os repasses da conciliação como conciliados.
  • Requisita repasses conciliados e não resolvidos: recupera os repasses conciliados que serão resolvidos no sistema integrador.
  • Atualiza repasses resolvidos: registra um grupo de títulos como resolvido.

Fluxo: Autenticação

Para utilizar os recursos de API do Koncili, deve-se utilizar o seguinte método de autenticação:

Fluxo: Token de acesso

URLs utilizadas nesse fluxo:

  • POST: /auth/token

Importante

As credenciais devem ser enviadas no formato base64.

Ex: codifique para base64 -> usuario@email.com:senha123 que se torna dGVzdGVAZW1haWwuY29tOnNlbmhhMTIz

Passe as credenciais codificadas no corpo da requisição da seguinte forma: 


                { 
                  "credentials": "dGVzdGVAZW1haWwuY29tOnNlbmhhMTIz" 
                }

Fluxo: Refresh Token

URLs utilizadas nesse fluxo:

  • POST: /auth/refresh-token

Fluxo: Envio de pedidos

Esse serviço recebe pedidos para então transformá-los em repasses que serão conciliados posteriormente.

Importante

Os pedidos devem ser enviados via operação POST e qualquer alteração de status que sofrer deverá ser realizado um novo request contendo todas as informações referentes ao pedido. A operação de atualização só poderá ser realizada se o pedido já tiver sido postado no Koncili.

Fluxo: envio de pedidos

URLs utilizadas nesse fluxo:

  • POST: /order

Fluxo: envio de pedidos e atualização

URLs utilizadas nesse fluxo:

  • POST: /order
  • PUT: /order/update

Fluxo: envio de pedidos antes de serem postados

URLs utilizadas nesse fluxo:

  • PUT: /order/update

Fluxo: deletar pedidos enviados

URLs utilizadas nesse fluxo:

  • POST: /order
  • DELETE: /order/{orderCode}/{channelName}

Ações:

  • Pedido tem pagamento aprovado: o pedido tem seu pagamento aprovado no Marketplace.
  • Envia pedido: pedido é enviado para o Koncili por uma operação POST gerando os repasses.
  • Pedido sofreu qualquer tipo de alteração: o status do pedido foi alterado para faturado, enviado, entregue ou cancelado. É necessário atualizar as informações no Koncili.
  • Deletar pedido: pedido é apagado da base de dados do Koncili e NÃO entrará em uma conciliação.

Fluxo: Baixa e resolução de repasses

Serviço destinado a baixa de repasses pela aplicação (ERP) do Seller. Para integração com fluxo de caixa do cliente.

Recupera todos os repasses que já foram conciliados pelo Koncili mas que NÃO foram resolvidos ou baixados na aplicação do Seller.

Importante

Essa requisição retorna por padrão apenas os repasses que foram conciliados na data da operação. É possível baixar um título de um pedido específico ou baixar todos os repasses conciliados dentro de um período informado via query.

Fluxo: Resolver repasses

Neste fluxo, a aplicação de integração fica responsável por consultar a API do Koncili toda vez que for iniciar o processo de baixa de repasses.

Recomendamos que este processo seja executado de 1 a 4 vezes por dia, não sendo necessário realizar consultas constantes.

URLs utilizadas nesse fluxo:

  • GET: /orderextract/unresolveds
  • PUT: /orderextract/resolve/{id}
    • (Baixa individual de títulos por id)
  • PUT: /orderextract/resolve/batch
    • (Baixa em lote de títulos)

Valores que serão atualizados pelo PUT:

  • resolvedInERP: recebe valor true indicando que o repasse já foi resolvido pela aplicação do cliente

Fluxo: Resolver repasses utilizando o callback de conciliações

Para utilizar este fluxo, a aplicação de integração deverá disponibilizar uma API Rest de acesso público seguindo os requisitos básicos listados na seção Ferramentas/Callback de conciliação desta documentação.

URLs utilizadas nesse fluxo:

  • POST: URL pública da aplicação de integração configurada no Koncili
  • GET: /orderextract/unresolveds
  • PUT: /orderextract/resolve/{id}
    • (Baixa individual de títulos por id)
  • PUT: /orderextract/resolve/batch
    • (Baixa em lote de títulos)

Valores que serão atualizados pelo PUT:

  • resolvedInERP: recebe valor true indicando que o repasse já foi resolvido pela aplicação do cliente

Fluxo: recuperar repasses já resolvidos

Também é possível recuperar todos os repasses que já foram baixados e resolvidos pela aplicação do Seller.

URLs utilizadas nesse fluxo:

  • GET: /orderextract/concilieds


Ações:

  • Requisita conciliados: requisita os repasses que já foram conciliados e não resolvidos.
  • Pedidos conciliados e não resolvidos: retorna os repasses de um pedido ou uma página com os repasses de vários pedidos que já foram conciliados e não resolvidos na aplicação integradora.
  • Resolve pedidos: os repasses são baixados e resolvidos na aplicação integradora.
  • Atualiza repasses resolvidos: os repasses que foram resolvidos são atualizados no Koncili.
  • Requisita resolvidos: requisita os repasses que já foram conciliados e resolvidos.