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 no VHub. O disparo acontece via CDC (Change Data Capture), garantindo que toda transição da máquina de estados do lote — provocada por automações internas, retornos de administradoras, webhooks recebidos ou ações manuais — seja entregue ao integrador.

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": "Cessao",
    "statusAnterior": "AguardandoEnvio",
    "statusAtual": "EnviadoAoFundo",
    "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": {
    "isTeste": "false",
    "origem": "vhub"
  }
}

🧾 Detalhamento dos Campos de `dados`¶

Campo	Tipo	Descrição
`idLote`	integer	Identificador do lote no VHub
`tipoOcorrencia`	string (enum)	Tipo de ocorrência do lote (ver tabela abaixo)
`statusAnterior`	string (enum) — null	Status anterior à alteração. `null` se for a primeira transição registrada para o lote
`statusAtual`	string (enum)	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`)¶

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

🔢 Status do Lote (`statusAnterior` / `statusAtual`)¶

Valor (string)	Significado
`EmDigitacao`	Lote em digitação/criação
`ValidandoPreElegibilidade`	Validação automática de elegibilidade antes da análise do gestor
`AprovacaoDaConsultoria`	Aguardando análise da consultoria
`AprovacaoDoGestor`	Aguardando análise do gestor
`ValidandoElegibilidade`	Validação automática de elegibilidade pós-aprovação
`ValidacaoDoCedente`	Aguardando aprovação do cedente
`RegistrandoBoletoBanco`	Registrando boletos em Open Banking (BV, Santander, etc.)
`EnviandoRegistradora`	Enviando duplicatas/CCBs para registradora (B3)
`EnviadoRegistradora`	Registrado na registradora
`AguardandoRetornoTransferenciaTitularidade`	Aguardando upload do retorno bancário de transferência
`AguardandoAssinaturasInterno`	Aguardando assinatura interna do termo de cessão
`AguardandoEnvio`	Pronto para envio à administradora
`EnviadoAoFundo`	Lote efetivamente enviado ao fundo/administradora
`AprovacaoDoGestorAdministradora`	Aguardando aprovação do gestor na administradora
`AguardandoAssinaturas`	Aguardando assinaturas externas (cedente, fundo, etc.)
`EfetivacaoDaBaixa`	Efetivação da baixa
`PagamentoDaCessao`	Aguardando pagamento da cessão
`TransferindoTitularidadeBoleto`	Transferindo titularidade dos boletos
`BaixarBoletosRejeitadosRecomprados`	Baixando boletos rejeitados/recomprados
`Finalizado`	Lote concluído com sucesso (estado terminal)
`Cancelado`	Lote cancelado (estado terminal)
`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/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: 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": "Cessao",
    "statusAnterior": "AguardandoEnvio",
    "statusAtual": "EnviadoAoFundo",
    "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": {
    "isTeste": "false",
    "origem": "vhub"
  }
}

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 /api/v1/lote/{id}.
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 (TipoRegistroBoleto, ExigeRegistroNaRegistradora, etc.).
Quando a transição é provocada por webhooks recebidos pelo VHub (Vortx, QiTech, OliveiraTrust), o evento é gerado com a dataHora do processamento interno, não a do webhook original.