7.2. Status do Lote alterado

🔔 Tipo de Notificação

Campo	Valor
tipoEvento	lote.status_alterado	Lote teve seu status alterado por automação ou ação manual
Id	4	Identificador do tipo de evento na tabela tipo_evento_webhook

---

🧾 Descrição

Esta notificação é enviada via POST para o endpoint configurado toda vez que a coluna status de um lote é alterada. Use este evento para acompanhar toda a jornada do lote desde a criação até a finalização ou rejeição.

---

📤 Payload Enviado

{
  "idWebhook": "019e0892-8d99-778c-9fa5-47bd07cd9ffb",
  "tipoEvento": "lote.status_alterado",
  "dataHora": "2026-05-08T14:23:11.512Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idLote": 1001,
    "tipoOcorrencia": 1,
    "statusAnterior": 4,
    "statusAtual": 5,
    "idOperacao": 101,
    "nomeOperacao": "Cessão FIDC Vertrau",
    "idCessionario": 201,
    "valorAquisicaoTotal": 985300.50,
    "valorNominalTotal": 1000000.00,
    "quantidadeTitulos": 25,
    "dataAlteracao": "2026-05-08T14:23:11.444Z"
  },
  "etiquetas": null
}

🧾 Detalhamento dos Campos de dados

Campo	Tipo	Descrição
idLote	integer	Identificador do lote no VeHub
tipoOcorrencia	integer (enum)	Código do tipo de ocorrência do lote (ver tabela abaixo)
statusAnterior	integer (enum) — null	Código do status anterior à alteração. null se for a primeira transição registrada para o lote
statusAtual	integer (enum)	Código do status atual após a alteração
idOperacao	integer — null	Identificador da operação vinculada ao lote
nomeOperacao	string — null	Nome legível da operação
idCessionario	integer — null	Identificador do cessionário (FIDC) que adquire os recebíveis
valorAquisicaoTotal	number — null	Valor de aquisição total do lote (em reais)
valorNominalTotal	number — null	Valor nominal total do lote (em reais)
quantidadeTitulos	integer — null	Quantidade de títulos vinculados ao lote
dataAlteracao	string (ISO 8601)	Momento exato da alteração de status (UTC)

---

🔢 Tipo de Ocorrência (tipoOcorrencia)

O campo é enviado como código numérico do enumerador:

Código	Nome	Significado
1	Cessao	Cessão de recebíveis (cedente → fundo)
2	Repasse	Repasse ao fundo (sem aquisição)
3	RecompraComAdiantamento	Recompra com adiantamento — cedente recompra título antes do vencimento
7	RecompraComSubstituicao	Recompra substituindo por outros títulos elegíveis
4	Resolucao	Resolução — desfaz a cessão (raros, geralmente por inadimplência irrecuperável)
5	LiquidacaoCedente	Liquidação por depósito do cedente
6	LiquidacaoSacado	Liquidação por depósito do sacado

---

🔢 Status do Lote (statusAnterior / statusAtual)

Os campos são enviados como código numérico do enumerador:

Código	Nome	Significado
1	EmDigitacao	Lote em digitação/criação
15	ValidandoPreElegibilidade	Validação automática de elegibilidade antes da análise do gestor
22	AprovacaoDaConsultoria	Aguardando análise da consultoria
2	AprovacaoDoGestor	Aguardando análise do gestor
14	ValidandoElegibilidade	Validação automática de elegibilidade pós-aprovação
3	ValidacaoDoCedente	Aguardando aprovação do cedente
18	RegistrandoBoletoBanco	Registrando boletos em Open Banking (BV, Santander, etc.)
16	EnviandoRegistradora	Enviando duplicatas/CCBs para registradora (B3)
12	EnviadoRegistradora	Registrado na registradora
20	AguardandoRetornoTransferenciaTitularidade	Aguardando upload do retorno bancário de transferência
17	AguardandoAssinaturasInterno	Aguardando assinatura interna do termo de cessão
4	AguardandoEnvio	Pronto para envio à administradora
5	EnviadoAoFundo	Lote efetivamente enviado ao fundo/administradora
13	AprovacaoDoGestorAdministradora	Aguardando aprovação do gestor na administradora
6	AguardandoAssinaturas	Aguardando assinaturas externas (cedente, fundo, etc.)
7	EfetivacaoDaBaixa	Efetivação da baixa
8	PagamentoDaCessao	Aguardando pagamento da cessão
19	TransferindoTitularidadeBoleto	Transferindo titularidade dos boletos
21	BaixarBoletosRejeitadosRecomprados	Baixando boletos rejeitados/recomprados
23	AguardandoDocumentos	Aguardando envio de documentos pelo cedente
24	AguardandoAprovacaoDocumental	Aguardando aprovação da documentação enviada
25	AptoParaEnvio	Lote validado documentalmente e apto para envio ao fundo
9	Finalizado	Lote concluído com sucesso (estado terminal)
10	Cancelado	Lote cancelado (estado terminal)
11	Rejeitado	Lote rejeitado (estado terminal)

Os estados terminais são Finalizado, Cancelado e Rejeitado. Após qualquer um deles, não há mais transições — exceto reativações manuais por administrador.

---

📪 Exemplo de envio

POST /webhook/vehub 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: lote.status_alterado
X-Webhook-Signature: sha256=fa1be9c4bc1e9b7a8a1e6f37f0e8a3d4f1e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "idWebhook": "019e0892-8d99-778c-9fa5-47bd07cd9ffb",
  "tipoEvento": "lote.status_alterado",
  "dataHora": "2026-05-08T14:23:11.512Z",
  "grupoEconomico": "MeuGrupo",
  "dados": {
    "idLote": 1001,
    "tipoOcorrencia": 1,
    "statusAnterior": 4,
    "statusAtual": 5,
    "idOperacao": 101,
    "nomeOperacao": "Cessão FIDC Vertrau",
    "idCessionario": 201,
    "valorAquisicaoTotal": 985300.50,
    "valorNominalTotal": 1000000.00,
    "quantidadeTitulos": 25,
    "dataAlteracao": "2026-05-08T14:23:11.444Z"
  },
  "etiquetas": null
}

Resposta esperada

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

{ "received": true }

---

🕒 Observações

• O campo statusAnterior pode ser null apenas na primeira transição registrada (criação do lote).
• Os valores de valorAquisicaoTotal e valorNominalTotal são informativos e refletem o momento da alteração — para fonte da verdade, use a API de consulta GET /public/v1/recebiveis/lotes/{idLote}.
• Em caso de transições muito rápidas (ex: EmDigitacao → ValidandoElegibilidade → AguardandoEnvio em segundos), múltiplas notificações chegarão em ordem não garantida. Use dataHora para ordenar e idWebhook para deduplicar.
• Estados intermediários como RegistrandoBoletoBanco ou EnviandoRegistradora só aparecem se a operação tiver as flags correspondentes ativas.