Operações pós-cessão
Saídas de operações do fundo fora do fluxo normal de liquidação. Cobre recompra, renegociação e reversão de cessão — cada uma com sua regra de quem paga o fundo e como o ativo é removido da carteira. Todos os endpoints retornam confirmação assíncrona via webhook.
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.
PrincípioA API expõe dois endpoints.
POST /api/loan/repurchaserecebe um campotypeque diferencia o tipo de saída do ativo, além de umrepurchase_valuee de umreason(texto livre, para auditoria).PATCH /api/loan/renegotiatetrata refinanciamentos.
2. Categorias suportadas (type)
type)type | Quando usar | Endpoint |
|---|---|---|
standard (recompra padrão) | Originador recompra o ativo por inadimplência, violação de elegibilidade, fraude ou solicitação | POST /api/loan/repurchase com type=standard |
compulsory_acquisition (aquisição compulsória) | Aquisição compulsória do ativo conforme regra do fundo | POST /api/loan/repurchase com type=compulsory_acquisition |
compulsory_repurchase (recompra compulsória) | Recompra compulsória pelo originador conforme regra do fundo | POST /api/loan/repurchase com type=compulsory_repurchase |
| renegociação | Refinanciamento — contrato atual é baixado e um novo contrato é cedido | PATCH /api/loan/renegotiate |
reasoné texto livre, não enumO motivo de negócio (ex.: reversão de cessão, resolução, inadimplência) vai no campo
reasoncomo texto livre — ele não altera o comportamento do endpoint. Quem determina o comportamento é otype.
3. Atores envolvidos
| Ator | Papel no fluxo |
|---|---|
| Integrador | Detecta o gatilho da operação pós-cessão e chama o endpoint correspondente |
| IORQ (gestora) | Valida a solicitação, registra a saída do ativo, sinaliza ADM, emite webhooks |
| administradora | Gera termo correspondente à categoria, coleta assinaturas, processa o evento financeiro |
| Bancarizador (quando aplicável) | Em reversões de cessão, devolve o valor diretamente ao fundo |
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
| Campo | Tipo | Descrição |
|---|---|---|
fund_id | UUID | FIDC da operação |
originator_proposal_code | string | Identificador da operação |
type | enum | standard, compulsory_acquisition, compulsory_repurchase |
repurchase_value | decimal | Obrigatório. Valor da recompra |
reason | string | Texto livre com o motivo (auditoria) |
Exemplo — recompra padrão:
curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/loan/repurchase' \
-H 'Authorization: Bearer eyJhbGciOi...' \
-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.
Há duas variantes: PATCH /api/loan/ (JSON puro) e PATCH /api/loan/renegotiate (multipart, quando há novos documentos de lastro). O corpo usa renegotiated_loans (as operações originais) e new_loan (a nova operação, no mesmo formato de uma cessão).
PATCH /api/loan/renegotiate · application/json ou multipart/form-data
Exemplo:
curl -X PATCH 'https://hs-receiver-app-production.iorq.com.br/api/loan/' \
-H 'Authorization: Bearer eyJhbGciOi...' \
-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": [ ]
}
}'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:
data.status | Quando dispara |
|---|---|
approved | Recompra/renegociação aceita e processada |
approved_renegotiation | Renegociação aprovada (nova operação na carteira) |
rejected | Recompra/renegociação recusada — ver data.reason |
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.