Webhooks do Ativo
Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status dos ativos individuais. Existem dois tipos de webhook: trade_receivables.asset_status_change para mudanças de status e trade_receivables.asset_creation para confirmação de criação do ativo.
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. O webhook de criação (asset_creation) é enviado a quem assina o status pending_eligibility. Entre em contato com integracao.dtvm@qitech.com.br para configurar. Entrega, tentativas e assinatura: veja Recebimento de Webhooks.
Fluxo de status do ativo
O ativo entra em pending_eligibility assim que é inserido no lote e, a partir da análise de elegibilidade, segue por um dos caminhos abaixo. O diagrama mostra o caminho principal; a lista completa de status está em Enumeradores de status do ativo.
Como ler o diagrama: azul = status intermediário · verde = ativo cedido e encarteirado · vermelho = status final de recusa ou descarte.
Estrutura do webhook
Todos os webhooks de ativo seguem a mesma estrutura base:
| Campo | Tipo | Descrição |
|---|---|---|
webhook_type | string | Tipo do webhook: trade_receivables.asset_status_change ou trade_receivables.asset_creation. |
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 ao qual o ativo pertence. |
asset_external_id | string | O external_id do ativo. |
asset_new_status | string | Novo status do ativo. |
assignment_configuration_key | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. |
fund_class_key | string | Identificador da classe do fundo associada ao lote. |
operation_type | string | Tipo de operação da configuração de cessão (ex.: unsecured_credit, duplicata_mercantil). |
asset_payload | object | Presente apenas no webhook de criação (asset_creation). Contém os dados do ativo conforme enviados na criação, com purchase_irr calculado dentro de credit_operation (CCB) ou contract (contratos). |
denial_reason | string | Presente em denied e registry_denied: origem da reprovação (os valores de denied_by). |
denial_metadata | object | Presente em denied e registry_denied quando há detalhe — por exemplo, as regras de elegibilidade reprovadas ou o motivo informado na remoção do ativo. |
assignment_configuration_keyA configuração de cessão é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na Homologação de Cedente.
Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa sob qual acordo o ativo está sendo cedido. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do ativo.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "STATUS",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Eventos por status
Ativo Criado
Enviado quando um ativo é inserido no lote com sucesso. Este webhook inclui o campo asset_payload com todos os dados da operação de crédito enviados na criação. O tipo do webhook é trade_receivables.asset_creation.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_eligibility",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit",
"asset_payload": {
"premiums": [
{
"total_value": 1.2,
"premium_type": "spread"
}
],
"asset_type": "ccb",
"credit_operation": {
"delay": {
"fine": {
"amount": 0.0,
"fine_type": "percentage"
},
"interest": {
"method": "compound",
"pre_fixed": {
"monthly_rate": 0.0,
"calendar_base": "workdays"
}
}
},
"borrower": {
"name": "João Pereira",
"email": "exemplo3@gmail.com",
"phone": {
"number": "948386674",
"area_code": "11"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "84",
"street": "RUA GILBERTO SABINO",
"country": "BRA",
"postal_code": "05425-020",
"neighborhood": "Pinheiros"
},
"person_type": "natural_person",
"natural_person": {
"birthdate": "1970-02-18",
"mother_name": "Natalia Nascimento"
},
"document_number": "969.698.790-03"
},
"contract": {
"cet": 0.0314,
"number": "0032226586/NNT",
"iof_value": 3.04,
"issue_date": "2024-04-24",
"issue_value": 93.05,
"signature_date": "2024-04-24",
"disbursement_date": "2024-04-24",
"disbursement_value": 62.1
},
"pre_fixed": {
"monthly_rate": 0.0179,
"calendar_base": "calendar_365"
},
"external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"installments": [
{
"face_value": 30.81,
"maturity_date": "2025-02-01",
"installment_number": 1
},
{
"face_value": 26.19,
"maturity_date": "2026-02-01",
"installment_number": 2
},
{
"face_value": 29.68,
"maturity_date": "2027-02-01",
"installment_number": 3
},
{
"face_value": 23.74,
"maturity_date": "2028-02-01",
"installment_number": 4
},
{
"face_value": 28.49,
"maturity_date": "2029-02-01",
"installment_number": 5
},
{
"face_value": 19.94,
"maturity_date": "2030-02-01",
"installment_number": 6
},
{
"face_value": 13.96,
"maturity_date": "2031-02-01",
"installment_number": 7
},
{
"face_value": 13.03,
"maturity_date": "2032-02-01",
"installment_number": 8
}
],
"principal_value": 93.05,
"amortization_type": "price",
"interest_rate_type": "pre_fixed",
"originator_document_number": "22.333.444/0001-81"
},
"total_purchase_value": 94.86
}
},
"webhook_type": "trade_receivables.asset_creation",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Aprovado na Elegibilidade — Pendente Documentação
Enviado quando o ativo é aprovado na análise de elegibilidade e a configuração de cessão exige documentos (duplicata mercantil e CT-e sempre passam por este status). Envie a documentação exigida pela Inserção de Documentos, se ainda não tiver enviado.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_documentation",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pré-Aprovado
Enviado quando o ativo é pré-aprovado, após validação bem-sucedida dos documentos (ou quando nenhuma documentação adicional é exigida). O ativo está apto para avançar para a etapa de formalização/registro.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pre_approved",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pendente Registro
Enviado quando o ativo pré-aprovado é encaminhado para a registradora. Só ocorre em configurações de cessão cujo registry_type exige registro — internal_registry, external_registry, registry_transfer ou unfit. O ativo permanece nesse status até a registradora responder.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_registry",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pendente Formalização
Status em que o ativo foi formalizado (registrado, quando a configuração exige registro) e está apto a seguir no lote até o encarteiramento. Hoje esta passagem não gera webhook, mesmo que o status esteja assinado. Acompanhe pela consulta do ativo ou pelo webhook do lote waiting_assets_to_formalize, nos webhooks do lote.
Ativo Concluído
Enviado quando o ativo foi encarteirado com sucesso na carteira do fundo. Este é o status final de um ativo bem-sucedido — a partir desse momento, o ativo encontra-se dentro do estoque do fundo.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "completed",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Reprovado na Elegibilidade
Enviado quando o ativo é reprovado — na elegibilidade, na validação de documentos ou da nota fiscal — ou removido do lote. O webhook traz denial_reason e, quando houver, denial_metadata. Um ativo reprovado por documento volta para pending_documentation se você enviar um novo documento.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Registro Recusado
Enviado quando a registradora recusa o registro do ativo. O ativo não segue para a formalização nem para o encarteiramento; quando o lote é aprovado, ele passa a denied. O webhook traz denial_reason e, quando houver, denial_metadata; o detalhe também aparece na consulta do ativo.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "registry_denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Ativo Descartado
Status do ativo descartado junto com o lote — por exemplo, no fechamento contábil do fundo. Depois da assinatura do Termo de Cessão, os ativos reprovados (denied) do lote também passam para discarded. Hoje esta passagem não gera webhook do ativo, mesmo que o status esteja assinado. Acompanhe pela consulta do ativo; o descarte do lote é avisado pelo webhook discarded dos webhooks do lote. Para retirar um ativo do lote, use a remoção de ativos, que leva o ativo a denied.