Ciclo de vida do direito creditório

1. O caminho feliz (visão simplificada)

stateDiagram-v2
    [*] --> received: POST /api/loan/
    received --> eligible: Passa nos critérios
    received --> ineligible: Falha de elegibilidade
    received --> rejected: Recusada
    eligible --> approved: Aprovada
    approved --> sent_acquisition_to_administrator: Sinalizada à ADM
    sent_acquisition_to_administrator --> acquired: ADM confirma aquisição
    acquired --> active: Operação no estoque
    active --> late: Parcela vencida sem pagamento
    late --> active: Pagamento regularizado
    active --> settled: Liquidação total
    active --> repurchased: POST /api/loan/repurchase
    active --> renegotiated: PATCH /api/loan/
    ineligible --> [*]
    rejected --> [*]
    settled --> [*]
    repurchased --> [*]
    renegotiated --> [*]

O diagrama mostra os estados principais. Entre eles existem estados intermediários de processamento com a administradora (ex.: sending_acquisition_to_administrator, processing_administrator, validated_administrator, waiting_acquisition, waiting_payment_to_borrower) e de registro (sent_to_registry, not_registered), além dos ciclos de renegociação (pre_approved_renegotiation → … → renegotiated) e recompra (pre_approved_repurchase → … → repurchased).

2. Grupos de estados

As mudanças relevantes para o integrador chegam via webhook LOAN_UPDATE — o data.status indica o que aconteceu (ex.: approved, rejected, settled_installment). Ver o Catálogo de eventos.

3. Estados de parcela (sub-ciclo)

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

stateDiagram-v2
    [*] --> active: Operação adquirida
    active --> paid: POST /api/installment/settle
    active --> partially_paid: Pagamento parcial
    active --> prepaid: POST /api/installment/prepayment
    active --> late: Vencida sem pagamento
    late --> paid_late: Pagamento com atraso
    paid --> settled: Baixa confirmada na ADM
    paid_late --> settled: Baixa confirmada na ADM
    settled --> [*]
    prepaid --> [*]

Estados adicionais cobrem o processamento da baixa com a administradora (sending/sent_settlement_to_administrator, settlement_conciliation_error), antecipação (waiting_prepayment), renegociação e recompra da parcela. Quando todas as parcelas atingem estado terminal, a operação migra para settled.

4. Consultar o estado atual

A qualquer momento, você pode consultar o estado de uma operação via GET /api/loan/ filtrando por originator_proposal_code (não há rota por path param):

curl 'https://hs-receiver-app-production.iorq.com.br/api/loan/?fund_id=SEU_FUND_ID&originator_proposal_code=OP-001' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "loans": [
    {
      "originator_proposal_code": "OP-001",
      "type": "ccb",
      "state": "active",
      "acquisition_value": 1000.0,
      "face_value": 1120.0,
      "created_at": "2026-05-13T11:00:00Z",
      "renegotiation_level": 0,
      "installments": [
        { "code": "1", "state": "settled", "face_value": 280.0, "due_date": "2026-06-13" },
        { "code": "2", "state": "active", "face_value": 280.0, "due_date": "2026-07-13" }
      ]
    }
  ],
  "cursor": {}
}

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 são recusadas. Tentar liquidar uma parcela de operação já recomprada resulta em erro (ou em webhook com data.status: invalid e data.reason: invalid_loan_state).
• Idempotência é preservada. Reenviar uma cessão com o mesmo originator_proposal_code não duplica a operação.
• Não assuma ordem de entrega dos webhooks. Reconcilie pelo estado atual da operação (consulta acima), não pela sequência de eventos recebidos.

6. Próximos passos