Catálogo de eventos

1. Envelope comum

Todo evento tem a mesma estrutura externa:

{
  "event": "<nome do evento>",
  "event_id": "evt_<uuid>",
  "originator_proposal_code": "<código da operação, quando aplicável>",
  "fund_id": "<UUID do fundo>",
  "timestamp": "2026-05-13T12:00:00Z",
  "data": { }
}

2. Eventos de cessão

`loan_received`

Dispara quando a cessão é aceita pela API e passa nas validações de schema e arquivo.

{
  "event": "loan_received",
  "data": { "received_at": "2026-05-13T11:00:00Z" }
}

`loan_approved`

Dispara quando a operação passa nos critérios de elegibilidade do fundo.

{
  "event": "loan_approved",
  "data": {
    "approved_at": "2026-05-13T11:02:34Z",
    "criteria_applied": ["concentration", "min_rate", "score"]
  }
}

`loan_rejected`

Dispara quando a operação é recusada — esquemática (faltam campos) ou de negócio (falha em elegibilidade).

{
  "event": "loan_rejected",
  "data": {
    "reason": "<código definido na homologação do fundo>",
    "reason_detail": "Explicação humana com os valores que causaram a rejeição",
    "criteria_failed": ["..."]
  }
}

`loan_term_signed`

Dispara quando todas as partes assinaram o termo de cessão na administradora.

{
  "event": "loan_term_signed",
  "data": {
    "term_id": "TERM-2026-05-13-0042",
    "signed_at": "2026-05-13T15:30:00Z"
  }
}

`disbursement_completed`

Dispara quando a administradora desembolsa o valor ao originador.

{
  "event": "disbursement_completed",
  "data": {
    "disbursed_value": 9500.00,
    "disbursed_at": "2026-05-14T09:00:00Z",
    "transfer_id": "TED-987654321"
  }
}

3. Eventos de liquidação

`installment_settled`

{
  "event": "installment_settled",
  "data": {
    "installment_code": "1",
    "settled_value": 280.00,
    "settled_at": "2026-05-30"
  }
}

`installment_prepaid`

{
  "event": "installment_prepaid",
  "data": {
    "prepayment_value": 1500.00,
    "settled_installments": ["6", "7", "8", "9", "10"],
    "remaining_balance": 320.00
  }
}

`installment_underpaid`

{
  "event": "installment_underpaid",
  "data": {
    "installment_code": "3",
    "expected_value": 280.00,
    "settled_value": 200.00,
    "difference": 80.00
  }
}

`loan_fully_settled`

{
  "event": "loan_fully_settled",
  "data": { "settled_at": "2027-04-13T10:00:00Z" }
}

4. Eventos pós-cessão

`repurchase_received`

{
  "event": "repurchase_received",
  "data": {
    "reason": "repurchase",
    "repurchase_value": 2540.00,
    "calculated_at": "2026-08-15T09:30:00Z"
  }
}

`repurchase_completed`

{
  "event": "repurchase_completed",
  "data": {
    "reason": "repurchase",
    "settled_value": 2540.00,
    "completed_at": "2026-08-16T14:00:00Z"
  }
}

`renegotiation_completed`

{
  "event": "renegotiation_completed",
  "data": {
    "original_proposal_code": "OP-001",
    "new_proposal_code": "OP-001-R1",
    "completed_at": "2026-09-01T10:00:00Z"
  }
}

5. Eventos meta

`webhook.ping`

Dispara automaticamente após registro de uma URL, para confirmar a configuração.

{
  "event": "webhook.ping",
  "data": { "message": "Webhook configured successfully" }
}

`webhook.delivery_failed`

Não é entregue — é gravado internamente e fica disponível via GET /webhook/{id}/deliveries. Útil para diagnóstico.

6. Filtrando eventos no registro

Você pode assinar só os eventos que interessam usando o campo events em POST /webhook:

{
  "url": "https://api.meudominio.com/iorq-webhooks",
  "events": ["loan_approved", "loan_rejected", "disbursement_completed"]
}

Use o curinga "*" para receber todos os eventos atuais e futuros. Recomendado em integrações em desenvolvimento ativo — você não perde eventos novos quando a IORQ os introduz.

7. Próximos passos

Continuar — Idempotência e reentrega

O que acontece quando você não consegue processar.

Mapa de estados — Ciclo de vida

Veja como cada evento se relaciona aos estados.