Ciclo de vida do direito creditório

1. Diagrama de estados completo

stateDiagram-v2
    [*] --> received: POST /loan
    received --> rejected: Falha de elegibilidade
    received --> approved: Passa nos critérios
    approved --> term_signing: ADM sinalizada
    term_signing --> term_signed: Partes assinam
    term_signed --> active: Desembolso confirmado
    active --> settled: Liquidação total
    active --> repurchased: POST /loan/repurchase
    active --> renegotiated: PATCH /loan/renegotiate
    rejected --> [*]
    settled --> [*]
    repurchased --> [*]
    renegotiated --> [*]

2. Estados em detalhe

Estado	Significado	Próximos válidos	Webhook
`received`	Operação aceita pela API, em fila de validação	`approved`, `rejected`	`loan_received`
`rejected`	Rejeitada por elegibilidade. Terminal	—	`loan_rejected`
`approved`	Passou nos critérios. ADM será sinalizada no próximo ciclo	`term_signing`	`loan_approved`
`term_signing`	ADM sinalizada, termo gerado, aguardando assinaturas	`term_signed`	—
`term_signed`	Termo assinado por todas as partes	`active`	`loan_term_signed`
`active`	Operação no estoque do fundo, gerando recebíveis	`settled`, `repurchased`, `renegotiated`	`disbursement_completed`
`settled`	Todas as parcelas liquidadas. Terminal	—	`loan_fully_settled`
`repurchased`	Recomprada pelo originador. Terminal	—	`repurchase_completed`
`renegotiated`	Substituída por nova operação. Terminal	—	`renegotiation_completed`

3. Estados de parcela (sub-ciclo)

Cada parcela de uma operação active tem seu próprio ciclo:

stateDiagram-v2
    [*] --> pending: Operação ativa
    pending --> settled: POST /installment/settle
    pending --> prepaid: POST /installment/prepayment
    pending --> overdue: Vencida sem pagamento
    overdue --> settled: Pagamento com atraso
    settled --> [*]
    prepaid --> [*]

Quando todas as parcelas atingem estado terminal, a operação migra de active para settled.

4. Consultar o estado atual

A qualquer momento, você pode consultar o estado de uma operação via GET /loan/{originator_proposal_code}:

curl 'https://hs-api.iorq.com.br/loan/OP-001' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "originator_proposal_code": "OP-001",
  "fund_id": "...",
  "status": "active",
  "state_history": [
    {"state": "received",     "at": "2026-05-13T11:00:00Z"},
    {"state": "approved",     "at": "2026-05-13T11:02:34Z"},
    {"state": "term_signing", "at": "2026-05-13T11:05:00Z"},
    {"state": "term_signed",  "at": "2026-05-13T15:30:00Z"},
    {"state": "active",       "at": "2026-05-14T09:00:00Z"}
  ],
  "installments_summary": {
    "total": 12,
    "pending": 10,
    "settled": 2,
    "overdue": 0
  }
}

5. Garantias de transição

Estados terminais não voltam. Uma operação repurchased não pode ser reativada — para reincorporá-la ao fundo, faça uma nova cessão.
Transições inválidas retornam 422. Tentar liquidar uma parcela de operação já recomprada resulta em erro com mensagem explicativa.
Idempotência é preservada. Reenviar uma ação em estado terminal não causa efeito — retorna o estado atual.
Ordem de webhooks é monotônica por originator_proposal_code. Você não recebe loan_approved antes de loan_received.

6. Próximos passos

Continuar — Critérios de elegibilidade

Por que received vira rejected ou approved.

Referência — Catálogo de eventos

Schema completo de cada evento de webhook.