Operações pós-cessão

POST /loan/repurchase · PATCH /loan/renegotiate

1. Quando usar este fluxo

Use os endpoints pós-cessão sempre que uma operação ativa no fundo precisar sair da carteira antes de ser liquidada normalmente. As razões são variadas — inadimplência prolongada, cancelamento da venda, refinanciamento, fraude, erro operacional — e cada uma tem regras próprias sobre quem ressarce o fundo e qual o instrumento jurídico aplicado.

📘

Princípio

A API expõe dois endpoints que cobrem todas as categorias via parametrização. POST /loan/repurchase recebe um campo reason que diferencia recompra, reversão e resolução. PATCH /loan/renegotiate trata refinanciamentos.

2. Categorias suportadas

3. Atores envolvidos

4. Fluxo end-to-end

sequenceDiagram
    participant INT as Integrador
    participant IORQ as IORQ
    participant ADM as Administradora

    INT->>IORQ: POST /loan/repurchase (reason)
    IORQ-->>INT: 200 OK
    IORQ->>IORQ: Valida operação + calcula valor
    IORQ->>INT: Webhook repurchase_received
    IORQ->>ADM: Sinaliza saída do ativo (com motivo)
    ADM->>ADM: Gera termo correspondente
    ADM->>IORQ: Confirma processamento
    IORQ->>INT: Webhook repurchase_completed

5. Passo a passo

5.1 Recompra, reversão e resolução

Todas as categorias de saída do ativo exceto renegociação usam o mesmo endpoint, diferenciadas pelo campo reason.

POST /loan/repurchase · application/json

Campos do payload

Exemplo — recompra padrão:

curl -X POST 'https://hs-api.iorq.com.br/loan/repurchase' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "originator_proposal_code": "OP-001",
    "reason": "repurchase",
    "reason_detail": "Inadimplência > 90 dias",
    "effective_date": "2026-08-15",
    "idempotency_key": "OP-001-repurchase"
  }'

Resposta:

{
  "originator_proposal_code": "OP-001",
  "status": "repurchase_pending",
  "reason": "repurchase",
  "repurchase_value": 2540.00,
  "calculated_at": "2026-08-15T09:30:00Z"
}

📘

Cálculo do valor por reason

A IORQ aplica a regra padrão da categoria quando repurchase_value é omitido. As regras refletem o estado da operação no momento da solicitação (parcelas pagas, juros corridos, etc.).

• repurchase → valor presente da curva remanescente
• integrated_repurchase → idem, debitado no próximo repasse
• cession_reversal → valor desembolsado original (operação não rodou)
• resolution → valor desembolsado menos parcelas já pagas

5.2 Renegociação

Em uma renegociação, a operação atual é recomprada pelo originador na curva e uma nova operação é cedida no lugar com novos termos. A API trata isso como uma única transação atômica.

PATCH /loan/renegotiate · application/json

Exemplo:

curl -X PATCH 'https://hs-api.iorq.com.br/loan/renegotiate' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_proposal_code": "OP-001",
    "new_proposal": {
      "originator_proposal_code": "OP-001-R1",
      "number_of_installments": 18,
      "acquisition_value": 2200.00,
      "installments": [ ]
    },
    "effective_date": "2026-09-01"
  }'

Após a renegociação, a operação original sai da carteira (mesmo efeito de repurchase) e a nova operação entra no fluxo normal de cessão — passa por elegibilidade, gera termo e desembolso.

5.3 Webhooks de confirmação

6. Estados terminais pós-cessão

stateDiagram-v2
    active --> repurchased: POST /loan/repurchase
    active --> reversed: reason=cession_reversal
    active --> resolved: reason=resolution
    active --> renegotiated: PATCH /loan/renegotiate
    active --> settled: Liquidação normal (ver Liquidação)
    repurchased --> [*]
    reversed --> [*]
    resolved --> [*]
    renegotiated --> [*]
    settled --> [*]

Todos os estados pós-cessão são terminais. Uma operação que sai por qualquer um deles não volta para active. No caso de renegociação, a operação original termina e uma nova operação (com novo originator_proposal_code) é criada.

7. Próximos fluxos