Pular para o conteúdo principal

Criação de lançamentos

Nesta página, você encontrará uma explicação sobre a criação de lançamentos na API do Koncili.

O processo completo de conciliação financeira envolve 3 etapas principais que garantem a rastreabilidade e precisão dos lançamentos:

1. Envio do pedido​

Envio inicial da transação com todos os detalhes financeiros. Esta etapa registra os componentes financeiros extracts (tipos aceitos: COMISSION, SHIP, RETURN_COMISSION, RETURN_SHIP e SALE) que serão posteriormente conciliados.

2. Envio do Repasse​

Agrupamento lógico de múltiplos pedidos para processamento em lote. Define o período financeiro e prepara o sistema para receber os lançamentos.

3. Execução dos lançamentos​

Envio completo obrigatório

Todos os componentes financeiros de um pedido devem ser enviados em uma única requisição. Não é possível adicionar lançamentos parciais ou complementares posteriormente.

Regra fundamental: Os lançamentos financeiros (releases) devem reproduzir exatamente os valores e tipos pré-registrados no pedido (extracts), mantendo o identificador único (marketplaceCode).

Tipos de lançamentos suportados​

Os tipos de lançamentos suportados estão detalhados na lista completa de tipos de lançamentos. Os principais tipos incluem:

  • SALE: Valor bruto das vendas (sempre positivo)
  • COMISSION: Taxas de comissão (sempre negativo)
  • SHIP: Custos de frete (positivo ou negativo)
  • RETURN_COMISSION: Estorno de comissões (sempre positivo)

Fluxo completo: Pedido → Conciliação → Lançamentos​

1. Envio do pedido​

O pedido contém a estrutura financeira completa através do array extracts. Cada item representa um componente financeiro distinto:

Pedido
{
  "marketplaceCode": "701-2798273-4005859",
  "channelName": "CHANNEL_NAME",
  "accountId": "19055",
  "status": "PAID_WAITING_DELIVERY",
  "createdDate": "2025-05-09T12:00:00Z",
  "approvedDate": "2025-05-09T12:00:00Z",
  "sendDate": "2025-05-09T12:00:00Z",
  "estimatedDeliveryDate": "2025-05-15T12:00:00Z",
  "deliveryDate": "2025-05-15T12:00:00Z",
  "cancelDate": null,
  "totalGrossValue": 203.63,
  // ... (outros campos foram omitidos)
  "extracts": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",          // Venda bruta
      "value": 203.63,         // Sempre positivo
      "expectedDate": "2025-06-05T12:00:00Z"
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",    // Taxa de comissão
      "value": -24.44,         // Sempre negativo
      "percentage": 12         // 12% de comissão
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",          // Custo de frete
      "value": -27.95          // Negativo (custo)
    }
  ]
}

2. Envio do Repasse​

A conciliação agrupa pedidos para processamento em lote. O campo releasesQtd deve corresponder exatamente ao número total de lançamentos financeiros de todos os pedidos incluídos:

Conciliação
{
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "periodInitDate": "2024-02-14T01:00:01Z",   // Início do período
  "periodEndDate": "2024-02-15T01:00:01Z",    // Fim do período
  "releasesQtd": 3,                           // Quantidade de lançamentos financeiros incluídos
  "totalNetValue": 203.63                     // Valor líquido total da conciliação
}

O envio do repasse deve retornar um JSON parecido com esse (o id retornado é o reconciliationId):

Retorno envio
{
    "id": 237    // ID único da conciliação
}
Importante

É enviado a quantidade de releases para apenas um lançamento por vez.

  • O reconciliationId retornado é obrigatório para os lançamentos
  • O período deve cobrir todas as datas de releasedDate dos lançamentos
  • O releasesQtd deve ser a soma exata de todos os lançamentos que serão enviados

3. Envio de lançamento​

Lançamentos
{
  "reconciliationId": 237,
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "marketplaceCode": "701-2798273-4005859",
  "status": "CONCLUDED",
  "createdDate": "2024-02-10T12:12:12Z",
  "releasedDate": "2024-02-10T13:13:13Z",
  "releaseType": "IN_CASH",
  "installment": 1,
  "installmentQuantity": 1,
  "releases": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",
      "value": 203.63
      },
      {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",
      "value": -24.44
      },
      {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",
      "value": -27.95
      }
  ]
}

Princípio de reapresentação de lançamentos​

  1. Correspondência exata de tipos: Os tipos em releases devem ser idênticos aos registrados em extracts
  2. Consistência de valores: Os valores devem ser idênticos aos do pré-registro
  3. Mesma quantidade: O número de itens em releases deve ser igual ao número de extracts
  4. Mesmo marketplaceCode: O identificador único deve ser mantido em todos os níveis

Validação de erros comuns​

Validações automáticas​

Campos mal formatados no payload de qualquer requisição dos processos supracitados serão apresentados na resposta, com mensagens de erro específicas e status HTTP 400 (Bad Request).

Boas práticas de implementação​

  1. Mantenha valores originais:
    Nunca recalcule valores - use exatamente os mesmos valores do pedido original.

  2. Preserve a ordem:
    Mantenha a mesma sequência de lançamentos entre pedido e conciliação.

  3. Valide antecipadamente:
    Verifique os tipos de lançamentos suportados pelo marketplace antes do envio.

  4. Gerencie períodos:
    Certifique-se de que todas as datas de lançamentos estão dentro do período definido na conciliação.