6.1. Envio dos créditos em conta¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/liquidacoes`

🧾 Descrição¶

Envia à plataforma VeFlow os créditos efetivamente liquidados em conta pelas credenciadoras (por exemplo, via PIX) em favor dos estabelecimentos comerciais (ECs).

Esses créditos são usados pelo motor de conciliação para casar cada valor recebido com as URs constituídas nos contratos. Como as credenciadoras transferem o valor exato de cada UR por contrato e por data, a conciliação é simplificada e automática.

O envio é feito em lote: um único idOperacao e uma única contaBancaria de destino, acompanhados de uma lista de créditos (liquidacoes). A resposta confirma o recebimento do lote e devolve o identificadorProcessamento, usado para acompanhar o casamento em 6.2. Consultar processamento de liquidações.

⚠️ O resultado da conciliação não vem nesta resposta: ele é informado por webhook — ver 3.3. Atualizações da UR.

📤 Requisição¶

📋 Payload (JSON)¶

{
  "idOperacao": 0,
  "contaBancaria": {
    "banco": 0,
    "agencia": "0000",
    "conta": "000000"
  },
  "liquidacoes": [
    {
      "data": "0000-00-00",
      "cnpj": "",
      "credenciadora": "",
      "arranjo": "",
      "valor": 0.00,
      "identificadorMovimentacao": "",
      "nomeOriginador": ""
    }
  ]
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
idOperacao	number	Sim	ID da operação atrelada (valor definido pelo time de implantação). Campo de nível raiz, vale para todo o lote.
contaBancaria	object	Sim	Conta bancária que recebeu os créditos. Campo de nível raiz, vale para todo o lote.
→ banco	number	Sim	Número do banco da conta bancária.
→ agencia	string	Sim	Agência da conta bancária.
→ conta	string	Sim	Número da conta bancária.
liquidacoes	array	Sim	Lista dos créditos liquidados em conta que serão conciliados com as URs dos contratos. Cada elemento é um crédito recebido, identificado pela combinação de data, EC, credenciadora, arranjo e valor.
→ data	string	Sim	Data em que o valor foi creditado, no formato `YYYY-MM-DD`.
→ cnpj	string	Sim	CNPJ do estabelecimento comercial (somente números, sem formatação).
→ credenciadora	string	Sim	CNPJ da credenciadora que efetuou o crédito (somente números).
→ arranjo	string	Sim	Sigla do arranjo de pagamento (ex.: `"MCC"`, `"VCC"`).
→ valor	number	Sim	Valor exato creditado na conta, com 2 casas decimais.
→ identificadorMovimentacao	string	Não	Identificador da movimentação no sistema de origem. É devolvido na notificação de conciliação, permitindo rastrear qual crédito casou com qual UR.
→ nomeOriginador	string	Não	Nome do estabelecimento comercial originário da UR. Ajuda a conciliar quando o CNPJ do ponto de venda não é o do originador.

Regras e formatos

data no formato YYYY-MM-DD.
cnpj e credenciadora: somente dígitos (ex.: 12345678000199).
valor deve ser o valor exato creditado, sem arredondamento e sem agrupar créditos distintos em um único item.
Um lote pode conter créditos de vários ECs, credenciadoras, arranjos e datas, desde que todos tenham caído na contaBancaria informada.

🧪 Exemplo de cURL¶

curl -X POST https://api.veflow.com/public/api/v1.1/cartao/liquidacoes \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 3c7a91d4-2f6b-4e18-8a05-b1d94e77c210" \
  -H "Content-Type: application/json" \
  -d '{
    "idOperacao": 1,
    "contaBancaria": {
      "banco": 1,
      "agencia": "1111",
      "conta": "1111111"
    },
    "liquidacoes": [
      {
        "data": "2025-09-10",
        "cnpj": "12345678000199",
        "credenciadora": "11111111000191",
        "arranjo": "VCC",
        "valor": 1500.00,
        "identificadorMovimentacao": "1B428B23-C0A8-46D5-AF2C-1AFFAFAAC653",
        "nomeOriginador": "LOJA EXEMPLO LTDA"
      },
      {
        "data": "2025-09-10",
        "cnpj": "12345678000199",
        "credenciadora": "11111111000191",
        "arranjo": "MCC",
        "valor": 842.35,
        "identificadorMovimentacao": "9D3F0C68-77A1-4B52-B0E9-5C4A2E8D1F77",
        "nomeOriginador": "LOJA EXEMPLO LTDA"
      }
    ]
  }'

📥 Responses¶

✅ 200 OK¶

{
  "identificadorProcessamento": "86A12031-E774-4D90-A065-8E078DAB8AB2",
  "mensagem": "Liquidações recebidas para conciliação!"
}

Campo	Tipo	Descrição
identificadorProcessamento	string	GUID do lote recebido. Use-o em 6.2. Consultar processamento de liquidações.
mensagem	string	Mensagem de confirmação.

O 200 OK indica que os créditos foram aceitos e entraram na fila do motor de conciliação da plataforma. Ele não afirma que houve casamento com URs.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'idOperacao' é obrigatório.",
    "Campo 'contaBancaria.banco' é obrigatório.",
    "liquidacoes[0].data inválido. Formato esperado: YYYY-MM-DD.",
    "liquidacoes[0].valor deve ser maior que zero."
  ]
}

🕒 Observações¶

Este endpoint não possui limite de horário para envio.
As liquidações devem ser enviadas após as 10:05, porque o processamento em lote das agendas ocorre às 10:00. Enviar antes disso pode conciliar contra uma posição de URs ainda não atualizada.
A conciliação é executada de forma recorrente: créditos que não casarem imediatamente continuam sendo reavaliados nas rodadas seguintes.
O resultado da conciliação é informado exclusivamente por webhook — ver 3.3. Atualizações da UR.
Para verificar o que a plataforma conseguiu casar do lote enviado: 6.2. Consultar processamento de liquidações.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.