Webhooks do Lote de Cessão

Ao longo do fluxo de cessão, o sistema envia webhooks para notificar mudanças de status do lote. Todos têm o tipo trade_receivables.assignment_status_change e identificam o lote pelo assignment_external_id informado na criação.

Configuração de webhooks

Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. A configuração define quais status você recebe: só são enviados os eventos assinados nela. Entre em contato com integracao.dtvm@qitech.com.br para configurar. Entrega, tentativas e assinatura: veja Recebimento de Webhooks.

Fluxo de status do lote

Como ler o diagrama: azul = status intermediário com webhook · tracejado = status sem webhook · verde = cessão concluída · vermelho = status final de recusa ou descarte.

A lista completa de status, inclusive os que não geram webhook, está em Enumeradores de status do lote.

Estrutura do webhook

Campo	Tipo	Descrição
webhook_type	string	Sempre trade_receivables.assignment_status_change.
webhook_datetime	string	Data e hora do envio, no formato YYYY-MM-DDTHH:MM:SSZ.
data	object	Dados do evento. Veja tabela abaixo.

Atributos de data

Campo	Tipo	Descrição
assignment_external_id	string	O external_id do lote informado na criação.
assignment_new_status	string	Novo status do lote.
assignment_configuration_key	string	Configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. Como um cedente pode ter mais de uma configuração ativa, ela indica sob qual acordo o evento aconteceu.
fund_class_key	string	Classe do fundo do lote.
signed_term_url	string	Só no webhook pending_payment, quando o Termo de Cessão foi assinado eletronicamente: URL pré-assinada para download do termo assinado, válida por 24 horas. Depois disso, use Documentos da Cessão.

Webhook Body

{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_manager_approval",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}

Eventos por status

O corpo é sempre o mesmo; muda o assignment_new_status.

assignment_new_status	Quando é enviado
pending_assets_insertion	Lote criado e pronto para receber ativos. Também quando um lote é reaberto.
completed_assets_insertion	Inserção de ativos encerrada. Também quando o lote volta do registro com ativos recusados pela registradora. Não é enviado para lote com assignment_date futura: ele passa por waiting_assignment_date e entra em completed_assets_insertion na data da cessão, sem webhook.
pending_eligibility	Todos os ativos foram analisados e o lote entrou na análise de elegibilidade.
pending_consultant_approval	Lote aprovado na elegibilidade, aguardando a aprovação da consultoria.
pending_manager_approval	Lote aprovado na elegibilidade (e pela consultoria, quando aplicável), aguardando a aprovação da gestora.
pending_assets_registry	Lote aprovado automaticamente, com ativos sendo registrados.
waiting_assets_to_formalize	Ativos registrados (ou lote aprovado automaticamente sem registro), aguardando formalização.
pending_assignment_term	Termo de Cessão sendo gerado.
pending_assignment_term_signature	Termo de Cessão enviado para assinatura. Consulte-o em Documentos da Cessão.
pending_custody	Aguardando custódia, conforme a configuração de cessão. Enviado só quando a configuração dispensa a assinatura do termo; depois da assinatura, a passagem para pending_custody não gera webhook.
pending_payment	Termo assinado (ou dispensado) e pagamento ao cedente em processamento. Pode trazer signed_term_url.
pending_assets_wallet_inclusion	Pagamento confirmado; ativos sendo encarteirados.
waiting_after_assignment_registry	Registro pós-cessão (registro diferido) enviado à registradora.
completed	Ativos encarteirados na carteira do fundo — cessão concluída. Em configurações com registro diferido, é enviado no encarteiramento, antes do registro pós-cessão.
denied	Lote reprovado: na elegibilidade, por todos os ativos terem sido reprovados, no registro, ou pela consultoria/gestora. Não volta para a esteira pela API.
discarded	Lote descartado — por exemplo, no fechamento contábil do fundo, quando ainda não tinha sido pago. Lotes denied também são descartados nesse momento.

Transições sem webhook

• A aprovação final feita pela API ou pelo portal (que leva o lote para pending_assets_registry ou waiting_assets_to_formalize) não gera webhook nessa transição. Use o status da resposta da aprovação.
• waiting_assignment_date, pending_send_to_signature, pending_assignment_term_validation e pending_after_assignment_documentation não geram webhook.
• A passagem para pending_custody depois da assinatura do Termo de Cessão.

Para conferir o status a qualquer momento, use a Recuperação do Lote.