7.5. Título Liquidado¶

🔔 Tipo de Notificação¶

Campo	Valor
`tipoEvento`	`titulo.liquidado`	Título foi liquidado (pago)
Id	`7`	Identificador do tipo de evento na tabela `tipo_evento_webhook`

🧾 Descrição¶

Esta notificação é enviada via POST para o endpoint configurado quando um título é liquidado — ou seja, quando o pagamento é confirmado e o título sai do estoque do fundo. Cobre as duas modalidades de liquidação:

LiquidacaoSacado — sacado (devedor) paga diretamente o título.
LiquidacaoCedente — cedente paga o título no lugar do sacado (típico em casos de coobrigação).

Use este evento para:

Confirmar a entrada de caixa correspondente ao recebível.
Atualizar o estoque do fundo (saída do título).
Reconciliar movimentações financeiras com o pagamento real.
Detectar liquidações parciais (pagamentoParcial: true).

📤 Payload Enviado¶

{
  "idWebhook": "019e0892-8d99-778c-9fa5-47bd07cd9ffb",
  "tipoEvento": "titulo.liquidado",
  "dataHora": "2026-06-08T09:15:42.122Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idTitulo": 2001,
    "numeroDocumento": "NF-000123",
    "especieTitulo": "DuplicataMercantil",
    "ocorrencia": "LiquidacaoSacado",
    "idLote": 1098,
    "idLoteTitulo": 3401,
    "idCedente": 301,
    "documentoCedente": "12.345.678/0001-90",
    "idSacado": 401,
    "documentoSacado": "98.765.432/0001-10",
    "dataVencimento": "2026-06-07",
    "valorNominal": 50000.00,
    "valorAquisicao": 48750.00,
    "dataExecucao": "2026-06-08T09:15:42.000Z",
    "valorPago": 50000.00,
    "pagamentoParcial": false
  },
  "etiquetas": {
    "isTeste": "false",
    "origem": "vhub"
  }
}

🧾 Detalhamento dos Campos de `dados`¶

Campo	Tipo	Descrição
`idTitulo`	integer	Identificador do título no VHub
`numeroDocumento`	string — null	Número do documento
`especieTitulo`	string (enum) — null	Espécie do título
`ocorrencia`	string (enum)	`LiquidacaoSacado` ou `LiquidacaoCedente`
`idLote`	integer	Identificador do lote de liquidação
`idLoteTitulo`	integer	Identificador do registro `lote × título` da liquidação
`idCedente`	integer — null	Identificador do cedente original
`documentoCedente`	string — null	CPF/CNPJ do cedente
`idSacado`	integer — null	Identificador do sacado
`documentoSacado`	string — null	CPF/CNPJ do sacado
`dataVencimento`	string (date) — null	Data de vencimento original do título
`valorNominal`	number — null	Valor nominal do título
`valorAquisicao`	number — null	Valor de aquisição registrado na cessão original (referência)
`dataExecucao`	string (ISO 8601)	Momento em que a liquidação foi efetivada (UTC)
`valorPago`	number — null	Valor efetivamente pago. Pode ser menor que `valorNominal` em pagamento parcial
`pagamentoParcial`	boolean	`true` quando o sacado/cedente pagou apenas parte do valor

🔢 Diferenciando as duas modalidades¶

`ocorrencia`	Quem paga	Cenário típico
`LiquidacaoSacado`	Sacado (devedor)	Pagamento normal do título no vencimento
`LiquidacaoCedente`	Cedente	Coobrigação — cedente paga após inadimplência do sacado

🔢 Pagamento Parcial¶

Quando pagamentoParcial = true:

O valorPago é o valor acumulado já liquidado (não apenas a parcela atual).
O título continua ativo no estoque do fundo até o pagamento total.
Novas notificações titulo.liquidado chegarão a cada nova liquidação parcial até a total.
A última notificação (quando o saldo é zerado) virá com pagamentoParcial = false.

📪 Exemplo de envio (liquidação completa)¶

POST /webhook/vhub HTTP/1.1
Host: app.cliente.com.br
Content-Type: application/json; charset=utf-8
X-Idempotency-Key: 019e0892-8d99-778c-9fa5-47bd07cd9ffb
X-Event-Type: titulo.liquidado
X-Webhook-Signature: sha256=4c8e3a...

{
  "idWebhook": "019e0892-8d99-778c-9fa5-47bd07cd9ffb",
  "tipoEvento": "titulo.liquidado",
  "dataHora": "2026-06-08T09:15:42.122Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idTitulo": 2001,
    "numeroDocumento": "NF-000123",
    "especieTitulo": "DuplicataMercantil",
    "ocorrencia": "LiquidacaoSacado",
    "idLote": 1098,
    "idLoteTitulo": 3401,
    "idCedente": 301,
    "documentoCedente": "12.345.678/0001-90",
    "idSacado": 401,
    "documentoSacado": "98.765.432/0001-10",
    "dataVencimento": "2026-06-07",
    "valorNominal": 50000.00,
    "valorAquisicao": 48750.00,
    "dataExecucao": "2026-06-08T09:15:42.000Z",
    "valorPago": 50000.00,
    "pagamentoParcial": false
  },
  "etiquetas": {
    "isTeste": "false",
    "origem": "vhub"
  }
}

📪 Exemplo de envio (liquidação parcial)¶

{
  "idWebhook": "019e0892-8d99-778c-9fa5-47bd07cd9ffc",
  "tipoEvento": "titulo.liquidado",
  "dataHora": "2026-06-08T09:15:42.122Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idTitulo": 2001,
    "numeroDocumento": "NF-000123",
    "especieTitulo": "DuplicataMercantil",
    "ocorrencia": "LiquidacaoSacado",
    "idLote": 1098,
    "idLoteTitulo": 3401,
    "idCedente": 301,
    "documentoCedente": "12.345.678/0001-90",
    "idSacado": 401,
    "documentoSacado": "98.765.432/0001-10",
    "dataVencimento": "2026-06-07",
    "valorNominal": 50000.00,
    "valorAquisicao": 48750.00,
    "dataExecucao": "2026-06-08T09:15:42.000Z",
    "valorPago": 25000.00,
    "pagamentoParcial": true
  }
}

Resposta esperada¶

HTTP/1.1 200 OK
Content-Type: application/json

{ "received": true }

🕒 Observações¶

Em casos de coobrigação, é comum receber primeiro um titulo.liquidado com ocorrencia = "LiquidacaoSacado" (pago pelo sacado, valor total) OU um titulo.liquidado com ocorrencia = "LiquidacaoCedente" (pago pelo cedente após inadimplência).
Em liquidações parciais, o valorPago é sempre acumulado desde a primeira liquidação parcial — você não precisa somar manualmente.
A dataExecucao é a data oficial da efetivação no VHub. Para a data real do crédito bancário, consulte a movimentação correspondente em /api/v1/movimentacao.
Após a liquidação total, o título passa para status Liquidado no fundo. Use lote.status_alterado com statusAtual = "Finalizado" para detectar fechamento do lote inteiro.