Entenda a API

A API Koncili vem para facilitar a integração com as aplicações de nossos clientes. Através da API é possível enviar os pedidos, os quais são necessários para a conciliação. No momento de recebimento do pedido o Koncili irá gerar uma expectativa (prévia dos repasses) para que posteriormente seja comparada com os repasses importados do Marketplace. Após isso é possível recuperar os repasses conciliados para que seja possível realizar a baixa (quitação) das contas à receber no sistema de gestão integrador.

Operações

Nós fazemos o nosso melhor para que todas as nossas URLs sejam RESTful. Nossas URLs podem suportar um dos quatro diferentes tipos de verbos http:

  • GET obtém informações sobre um recurso.
  • POST cria um recurso.
  • PUT atualiza um recurso.
  • DELETE exclui um recurso.

Como utilizar a API

Para utilizar nossa API é necessário:

  • Obter um Token de acesso válido.
  • Conhecer nossas estruturas e regras.
  • Construir sua aplicação e utilizar nossas ferramentas para seus testes.

Acesso

É necessário informar um token para todas as URLs que serão acessadas. O nome gumgaToken deverá ter um valor informado via Header. Você pode obter um token de acesso solicitando ao nosso suporte.

Estruturas e regras

Consulta de recursos

As requisições que recuperam os pedidos podem ser apenas o registro solicitado ou uma página com vários registros.

Por registro

Requisições por ID retornarão apenas um único registro. Uma requisição que recupera o pedido por order code irá retornar registros para todos os tipos de repasses que foram gerados para aquele pedido.

Por páginas

Os repasses serão retornados em uma página com cabeçalho e uma quantidade limitada de registros. Os parâmetros que alteram a forma como a página é retornada são:

  • limit: indica a quantidade de repasses a serem retornados, máximo de 100.
  • offset: indica a partir de qual repasse a consulta irá começar.
  • initDate: indica qual a data inicial do período de retorno.
  • endDate: indica qual a data final do período de retorno.
  • content: lista com todos os registros encontrados naquela configuração.
É possível consultar os exemplos de retorno para cada requisição clicando aqui.

Envio de recursos

As informações que são passadas pelo body ou via query da requisição merecem um cuidado especial na hora de serem enviadas.

Markeplaces aceitos

O Koncili recebe pedidos somente da B2W, Netshoes, Mercado Livre, Via Varejo, Walmart, Magazine Luiza e Amazon. O atributo channelName deverá ser enviado com um dos seguintes valores:

  • B2W
  • NETSHOES
  • MERCADOLIVRE
  • CNOVA (Via Varejo)
  • WALMART
  • MAGALU (Magazine Luiza)
  • AMAZON

Datas

Atributos do tipo data devem ser enviados no body no formato yyyy-MM-dd'T'HH:mm:ss.SSSZ (Ex.: 2017-11-30T15:55:21.000+0000), e devem ser enviadas via query no formato yyyy-MM-dd (Ex.: 2017-11-30).

Dimensões

Dimensões de comprimento, largura e altura deverão ser enviadas em centímetros e peso deverá ser enviado em kilos.

Status do pedido

Os status do pedido aceitos pelo Koncili são:

  • PAID_WAITING_SHIP: pago.
  • INVOICED: faturado.
  • PAID_WAITING_DELIVERY: enviado.
  • CONCLUDED: concluido/entregue.
  • CANCELED: cancelado.

Métodos de pagamento

Os métodos de pagamento aceitos pelo Koncili são:

  • DEBIT_CARD: cartão de débito.
  • CREDIT_CARD: cartão de crédito.
  • BILLET: boleto.
  • VOUCHER: voucher.
  • OTHER: outro.

Informações adicionais

  • OrderIdHubOrigin: esse atributo representa o ID do pedido no sistema integrador.

É possível consultar os exemplos de envio de recursos para algumas requisições clicando aqui.

Recursos disponíveis

Envio de pedidos

Esse recurso permite consultar, enviar, atualizar e deletar um pedido no Koncili. Com o envio do pedido será possível realizar a conciliação com os repasses do Marketplace, e assim verificar se estão sendo pagos corretamente.

Regras para Marketplaces

Para alguns Marketplaces as regras de repasses são diferentes.

Regras Gerais

  • Status: a partir do status do pedido alguns repasses adicionais poderão ser gerados;

B2W

  • Atributo order_code: código de uma das entregas (cada entrega é tratado como um pedido);
  • Atributo de item idInMarketplace: código do pedido (Ex.: 02-123456789);
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para a B2W.

Netshoes

  • Atributo de item idInMarketplace: Deve ser enviado com o mesmo valor do atributo orderCode;
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para a Netshoes.

Mercado Livre

  • Atributo shippingId: obrigatório para o Mercado Livre. Código do Shipment criado no Marketplace.
  • Atributo comissionType: obrigatório para o Mercado Livre. Tipo do anúncio Clássico (CLASSIC) ou premium (PREMIUM) da venda.
  • Atributo orderCode: código do pedido. Se feito no carrinho, esse código é o mesmo que shippingId, se feito fora "do carrinho" é o mesmo que idInMarketplace;
  • Atributo idInMarketplace: código de uma venda. Se o pedido não for feito "no carrinho" deve ser o mesmo valor que o código do pedido (orderCode);
  • Importante: o Mercado Livre possui algumas regras muitos específicas que só são possiveis de encontrar via integração direta com o Marketplace. O Koncili já possui essa integração, então recomendamos que os pedidos não sejam enviados via integração Parceiro x Koncili, e sim permitir que nossa aplicação busque diretamente no Marketplace.

Via Varejo

  • Atributo trackingType: Deve ser enviado para o Koncili quando o pedido utiliza o Envvias da Via Varejo para a logistica. E o valor desse atributo é ENVVIAS. Se o pedido não utiliza Envvias então não precisa ser incluído no Json, pois será gerado erro caso informado valor diferente de ENVVIAS.
  • Atributo de item trackingType: Tem o mesmo comportamento do item acima.
  • Atributo de item idInMarketplace: Deve ser enviado com o mesmo valor do atributo orderCode;
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para a Via Varejo.

Magazine Luiza

  • Atributo de item idInMarketplace: Deve ser enviado com o mesmo valor do atributo orderCode;
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para o Magazine Luiza.

Amazon

  • Atributo de item idInMarketplace: Deve ser enviado com o mesmo valor do atributo orderCode;
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para a Amazon.

Walmart

  • Atributo de item idInMarketplace: Deve ser enviado com o mesmo valor do atributo orderCode;
  • Atributos não utilizados: os atributos shippingId e comissionType não serão necessários para o Walmart.

Cuidados especiais

  • Atualização dos pedidos: sempre que um pedido sofrer qualquer tipo de alteração de status, por exemplo, ser faturado, enviado, entregue ou cancelado, é necesário atualizar essas informações no Koncili.
  • Vigência: se não existir vigência e suas comissões configuradas para o pedido enviado, o pedido não poderá ser processado. Esses dados são previamente configurados pelo Seller na aplicação do Koncili.
  • Status faturado: se o status do pedido for INVOICED, então é requerido a data e número da nota fiscal do pedido.
  • Status enviado: se o status do pedido for PAID_WAITING_DELIVERY, então é requerido a data de envio do pedido.
  • Status entregue: se o status do pedido for CONCLUDED, então é requerido a data e número da nota fiscal e a data de envio do pedido.
  • Status cancelado: se o status do pedido for CANCELADO, então é requerido a data de cancelamento do pedido.
  • Código do item e categoria: se existir comissão por produto ou categoria, então o código do item e da categoria devem ser previamente cadastrados nas comissões de vigência com seus respectivos percentuais de comissão.
  • Valor total: o atributo 'totalNetValue' é o valor total do pedido. Esse valor deve ser igual a soma de todos os itens mais frete e ou, a soma de todos os pagamentos. No valor total já devem estar incluídos o valor do frete e dos juros e descontado o valor dos descontos.
  • Valor total do frete: o atributo 'totalFreightValue' é o valor total do frete. Esse valor deve ser igual a soma de todos os fretes dos itens do pedido.
Clique aqui para conferir mensagens de erro que serão retornadas em algumas situações.

Deletar um pedido

  • Um pedido poderá ser deletado do Koncili desde que NUNCA tenha entrado em uma conciliação.
  • Após o pedido ser deletado é possível re-enviar o pedido com novas informações.
  • Essa operação não poderá ser desfeita e as informações apagadas serão perdidas.

É possível conferir alguns exemplos de envio de pedidos clicando aqui.

Baixa e resolução de repasses

Esse recurso permite recuperar os repasses do pedido após serem conciliados com os repasses do Marketplace gerando divergências ou não. Dessa forma é possível identificar quais foram os valores reais pagos pelo Marketplace e atualizar o sistema de gestão do Seller.

Informações importantes

  • Resolução de pedidos ou repasses é quando o sistema integrador recupera os repasses gerados pelo Koncili que foram conciliados com os repasses do Marketplace para que seja feita a baixa dos valores que o Marketplace pagou ao Seller.
  • Um pedido poderá ser recuperado após a conciliação que ele entrou ser finalizada pelo Seller.
  • O recurso retorna por padrão os pedidos que foram conciliados na data da requisição.
  • Após os pedidos serem recuperados, é necessário informar ao Koncili que eles já foram resolvidos no sistema integrador.

Clique aqui para visualizar um exemplo de baixa de títulos.