Operações pós-cessão

POST /api/loan/repurchase · PATCH /api/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.

Se a operação deve permanecer na carteira e o que muda é só a data de vencimento de parcelas em aberto, o fluxo é outro — Alteração de vencimento (PATCH /api/installment/due-date).

📘

Princípio

A API expõe dois endpoints. POST /api/loan/repurchase recebe um campo type que diferencia o tipo de saída do ativo, além de um repurchase_value e de um reason (texto livre, para auditoria). PATCH /api/loan/renegotiate trata refinanciamentos.

2. Categorias suportadas (type)

🚧

reason é texto livre, não enum

O motivo de negócio (ex.: reversão de cessão, resolução, inadimplência) vai no campo reason como texto livre — ele não altera o comportamento do endpoint. Quem determina o comportamento é o type.

3. Atores envolvidos

4. Fluxo end-to-end

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

    INT->>IORQ: POST /api/loan/repurchase (type + repurchase_value)
    IORQ-->>INT: 201 Created
    IORQ->>IORQ: Valida operação
    IORQ->>ADM: Sinaliza saída do ativo (com motivo)
    ADM->>ADM: Gera termo correspondente
    ADM->>IORQ: Confirma processamento
    IORQ->>INT: Webhook LOAN_UPDATE (status: approved/rejected)

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 type.

POST /api/loan/repurchase · application/json

Campos do payload

Exemplo — recompra padrão:

curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/loan/repurchase' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'iorq-fund-id: 374485cf-f6df-467c-b91d-9f14082c6f36' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
    "originator_proposal_code": "OP-001",
    "type": "standard",
    "repurchase_value": 2540.00,
    "reason": "Inadimplência > 90 dias"
  }'

Resposta (201):

{
  "status": "created",
  "message": "Loan repurchase received successfully"
}

📘

Valor da recompra

repurchase_value é obrigatório — a IORQ não calcula o valor automaticamente. Informe o valor conforme a regra acordada para o fundo e o tipo da operação.

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. O corpo usa renegotiated_loans (as operações originais que serão baixadas) e new_loan (a nova operação, no mesmo formato de uma cessão).

Há duas variantes, escolhidas pela existência (ou não) de novos documentos de lastro para a nova operação:

Campos do payload

Exemplo — variante JSON:

curl -X PATCH 'https://hs-receiver-app-production.iorq.com.br/api/loan/' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'iorq-fund-id: 374485cf-f6df-467c-b91d-9f14082c6f36' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
    "renegotiated_loans": [ { "originator_proposal_code": "OP-001" } ],
    "new_loan": {
      "originator_proposal_code": "OP-001-R1",
      "banker_cnpj": "...",
      "product_type": "financing",
      "number_of_installments": 18,
      "acquisition_value": 2200.00,
      "installments": [ ]
    }
  }'

Exemplo — variante multipart (com novos documentos de lastro):

curl -X PATCH 'https://hs-receiver-app-production.iorq.com.br/api/loan/renegotiate' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'iorq-fund-id: 374485cf-f6df-467c-b91d-9f14082c6f36' \
  -F 'renegotiation_data={"fund_id":"...","renegotiated_loans":[{"originator_proposal_code":"OP-001"}],"new_loan":{"originator_proposal_code":"OP-001-R1","banker_cnpj":"...","product_type":"financing","number_of_installments":18,"acquisition_value":2200.00,"backing_documents":[{"type":"renegotiation_document","value":"CD-OP-001-R1"}],"installments":[]}}' \
  -F '[email protected]'

Documento de lastro da renegociação — não-assinado e assinado

O instrumento da renegociação é a Confissão de Dívida, e ela entra em dois momentos, com dois type distintos:

Envie a Confissão de Dívida ainda não assinada como renegotiation_document já na renegociação — ela não precisa estar assinada para ser aceita e validada; o cronograma de parcelas é sempre reconferido contra a nova operação. Quando a via assinada existir, anexe-a como renegotiation_signature via POST /api/loan/files — é ela que valida a assinatura e faz a operação avançar para received_renegotiation_signature.

Formato do arquivo: PDF ou DOCX

Só a via não assinada (renegotiation_document, em PATCH /api/loan/renegotiate) aceita DOCX além de PDF.

Continuam valendo os mesmos limites da cessão: até 5 arquivos, 2 MB cada, e o nome do arquivo sem extensão precisa bater com backing_documents[].value (CD-OP-001-R1.docx ↔ "value": "CD-OP-001-R1").

Antes de aceitar o arquivo, a IORQ verifica que ele é um DOCX bem formado e que o conteúdo é seguro. Um arquivo que não passe é recusado com 400 e a resposta traz um código de motivo. Se um documento seu for recusado e o motivo não for claro, encaminhe o código retornado ao suporte.

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

Como todo o restante, a confirmação vem em um webhook LOAN_UPDATE com o resultado em data.status:

6. Estados terminais pós-cessão

stateDiagram-v2
    active --> repurchased: POST /api/loan/repurchase
    active --> renegotiated: PATCH /api/loan/renegotiate
    active --> settled: Liquidação normal (ver Liquidação)
    repurchased --> [*]
    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