4.1. Informar Liquidação¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1/duplicata-escritural/liquidacoes`

🧾 Descrição¶

Informa ao sistema a liquidação de uma ou mais duplicatas escriturais. Cada liquidação deve conter os dados da duplicata, os valores liquidados, o instrumento de pagamento utilizado e as informações do pagador e beneficiário.

📤 Requisição¶

📋 Payload (JSON)¶

{
  "tipoFluxoLiquidacao": 1,
  "liquidacoes": [
    {
      "codigoIdentificacaoDuplicata": "DUP-2025-001",
      "sacadorDocumento": "12345678000199",
      "dataLiquidacao": "2025-10-01",
      "valorLiquidado": 10000.00,
      "tipoInstrumentoPagamento": 2,
      "identificadorUnicoDuplicata": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
      "sacadoDocumento": "98765432000155",
      "dataVencimentoDuplicata": "2025-10-01",
      "tipoLiquidacao": 1,
      "indicadorValorParcial": false,
      "valorRemanescente": 0.00,
      "beneficiario": {
        "documento": "12345678000199",
        "nomeRazaoSocial": "Empresa Cedente LTDA"
      },
      "pagador": {
        "tipoDocumento": 2,
        "numeroDocumento": "98765432000155"
      },
      "instrumentoGerado": {
        "tipoInstrumentoPagamento": 2,
        "formaPagamento": 1,
        "pix": {
          "tipoChave": 2,
          "chave": "12345678000199"
        }
      }
    }
  ]
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Obrigatório	Descrição
tipoFluxoLiquidacao	integer	Sim	Tipo do fluxo de liquidação (ver TipoFluxoLiquidacao)
liquidacoes	array	Sim	Lista de liquidações a informar

🔹 liquidacoes[]¶

Campo	Tipo	Obrigatório	Descrição
codigoIdentificacaoDuplicata	string	Sim	Código de identificação da duplicata
sacadorDocumento	string	Sim	CNPJ/CPF do sacador (somente números)
dataLiquidacao	string	Sim	Data em que a liquidação ocorreu (YYYY-MM-DD)
valorLiquidado	number	Sim	Valor efetivamente liquidado
tipoInstrumentoPagamento	integer	Sim	Instrumento de pagamento utilizado (ver TipoInstrumentoPagamento)
identificadorUnicoDuplicata	string	Sim	GUID único da duplicata
sacadoDocumento	string	Sim	CNPJ/CPF do sacado (somente números)
dataVencimentoDuplicata	string	Sim	Data de vencimento original da duplicata (YYYY-MM-DD)
tipoLiquidacao	integer	Sim	Tipo da liquidação (ver TipoLiquidacao)
indicadorValorParcial	boolean	Sim	Indica se o valor liquidado é parcial
valorRemanescente	number	Sim	Valor remanescente após liquidação parcial (0 quando total)
beneficiario	object	Sim	Dados do beneficiário do pagamento
pagador	object	Sim	Dados do pagador
instrumentoGerado	object	Sim	Instrumento de pagamento gerado

🔹 beneficiario¶

Campo	Tipo	Obrigatório	Descrição
documento	string	Sim	CNPJ/CPF do beneficiário (somente números)
nomeRazaoSocial	string	Sim	Nome ou razão social do beneficiário

🔹 pagador¶

Campo	Tipo	Obrigatório	Descrição
tipoDocumento	integer	Sim	Tipo do documento (ver TipoDocumentoPessoa)
numeroDocumento	string	Sim	CPF ou CNPJ do pagador (somente números)

🔹 instrumentoGerado¶

Campo	Tipo	Obrigatório	Descrição
tipoInstrumentoPagamento	integer	Sim	Instrumento de pagamento (ver TipoInstrumentoPagamento)
formaPagamento	integer	Sim	Forma de pagamento (ver FormaPagamento)
boleto	object	Condicional	Dados do boleto (quando instrumento = 1)
pix	object	Condicional	Dados do PIX (quando instrumento = 2)
contaRecebimento	object	Condicional	Dados da conta de recebimento (quando instrumento = 3)

🔹 instrumentoGerado.boleto¶

Campo	Tipo	Obrigatório	Descrição
tipoBoleto	integer	Sim	Tipo do boleto (ver TipoBoleto)
numeroLinhaDigitavel	string	Sim	Linha digitável do boleto

🔹 instrumentoGerado.pix¶

Campo	Tipo	Obrigatório	Descrição
tipoChave	integer	Sim	Tipo da chave PIX (ver TipoChavePix)
chave	string	Sim	Valor da chave PIX

🔹 instrumentoGerado.contaRecebimento¶

Campo	Tipo	Obrigatório	Descrição
tipoConta	integer	Sim	Tipo da conta (ver TipoConta)
cpfCnpjTitularConta	string	Sim	CPF ou CNPJ do titular (somente números)
ispb	string	Sim	Código ISPB do banco
compe	string	Sim	Código COMPE do banco
agencia	string	Sim	Número da agência
digitoAgencia	string	Sim	Dígito verificador da agência
conta	string	Sim	Número da conta
digitoConta	string	Sim	Dígito verificador da conta

🔢 Enumeradores¶

TipoFluxoLiquidacao¶

Código	Significado
1	Baixa por liquidação

TipoLiquidacao¶

Código	Significado
1	Parcial
2	Total

TipoInstrumentoPagamento¶

Código	Significado
1	Boleto
2	PIX
3	TED

FormaPagamento¶

Código	Significado	Descrição
1	Boleto	Pagamento via boleto
2	PIX	Pagamento via PIX
3	TED	Pagamento via TED
4	TEF	Transferência eletrônica
5	DOC	Documento de crédito

TipoDocumentoPessoa¶

Código	Significado
1	CPF
2	CNPJ

TipoChavePix¶

Código	Significado
1	CPF
2	CNPJ
3	E-mail
4	Telefone
5	Chave Aleatória

TipoBoleto¶

Código	Significado
1	DDA
2	Carnê
3	Recorrente
4	Dinâmico

TipoConta¶

Código	Significado
1	Corrente
2	Poupança
3	Escrow

🧪 Exemplo de cURL¶

curl -X POST https://api.vehub.com.br/public/api/v1/duplicata-escritural/liquidacoes \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoFluxoLiquidacao": 1,
    "liquidacoes": [
      {
        "codigoIdentificacaoDuplicata": "DUP-2025-001",
        "sacadorDocumento": "12345678000199",
        "dataLiquidacao": "2025-10-01",
        "valorLiquidado": 10000.00,
        "tipoInstrumentoPagamento": 2,
        "identificadorUnicoDuplicata": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
        "sacadoDocumento": "98765432000155",
        "dataVencimentoDuplicata": "2025-10-01",
        "tipoLiquidacao": 1,
        "indicadorValorParcial": false,
        "valorRemanescente": 0.00,
        "beneficiario": {
          "documento": "12345678000199",
          "nomeRazaoSocial": "Empresa Cedente LTDA"
        },
        "pagador": {
          "tipoDocumento": 2,
          "numeroDocumento": "98765432000155"
        },
        "instrumentoGerado": {
          "tipoInstrumentoPagamento": 2,
          "formaPagamento": 1,
          "pix": {
            "tipoChave": 2,
            "chave": "12345678000199"
          }
        }
      }
    ]
  }'

📥 Responses¶

✅ 200 OK¶

{
  "mensagem": "Liquidações informadas com sucesso!",
  "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
  "identificadorProcessamento": null
}

✅ 202 Accepted¶

{
  "mensagem": "Liquidações recebidas e serão processadas em breve.",
  "identificadorProcessamento": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Duplicata não encontrada.",
    "Valor liquidado superior ao valor da duplicata."
  ]
}

🕒 Observações¶

Para liquidações parciais, informe indicadorValorParcial = true e o valorRemanescente com o saldo devedor.
Múltiplas liquidações podem ser enviadas em um único request através do array liquidacoes.
Quando o retorno for 202 Accepted, o processamento ocorrerá de forma assíncrona.