Liquidação

POST /api/installment/settle · POST /api/installment/prepayment

1. Quando usar este fluxo

Use os endpoints de liquidação quando o tomador da operação efetuou o pagamento de uma ou mais parcelas, em qualquer canal (débito automático, boleto, Pix, transferência). A IORQ não recebe o pagamento diretamente — ela apenas registra a baixa no estoque do fundo a partir da notificação do integrador.

📘

Princípio

A IORQ confia na notificação do integrador. A conciliação entre o que entrou na conta vinculada do fundo e o que foi notificado é uma etapa posterior, conduzida pela administradora junto ao custodiante — não exposta nesta API.

Tipos de liquidação

2. Atores envolvidos

3. Fluxo end-to-end

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

    TOMADOR->>INT: Paga parcela (débito, boleto, Pix...)
    INT->>INT: Registra o pagamento internamente
    INT->>IORQ: POST /api/installment/settle
    IORQ-->>INT: 201 Created
    IORQ->>IORQ: Processa baixa + atualiza estoque
    IORQ->>INT: Webhook LOAN_UPDATE (status: settled_installment)
    IORQ->>ADM: Sinaliza baixa

4. Pré-requisitos

• Operação ativa no fundo (já cedida e desembolsada — ver cessão)
• Pagamento recebido e identificado pelo integrador
• Token Bearer JWT válido (ver Autenticação)
• Endpoint HTTPS público para receber webhooks de confirmação

5. Passo a passo

5.1 Notificar liquidação de parcela

Para cada parcela paga (na curva, com atraso ou a menor), envie uma chamada para POST /api/installment/settle. Cada chamada registra a liquidação de uma parcela.

POST /api/installment/settle · application/json

Campos do payload

Exemplo de request:

curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/installment/settle' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
    "originator_proposal_code": "OP-001",
    "code": "1",
    "nosso_numero": "00012345",
    "paid_amount": 280.00,
    "payment_date": "2026-05-30",
    "is_partial_payment": false
  }'

Resposta (201):

{
  "status": "settled",
  "message": "Installment settled successfully"
}

5.2 Liquidação antecipada

Use POST /api/installment/prepayment quando o tomador antecipa pagamento — quita uma ou mais parcelas futuras antes do vencimento. A IORQ recalcula juros e identifica quais parcelas foram quitadas pelo valor antecipado. Há também POST /api/installment/prepayment/v2 para antecipação envolvendo múltiplas operações em uma chamada.

POST /api/installment/prepayment · application/json

Campos do payload

Exemplo de request:

curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/installment/prepayment' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
    "identifier": { "originator_proposal_code": "OP-001" },
    "code": "6",
    "due_date": "2026-06-15",
    "total_prepayment_amount": 1500.00,
    "prepayment_installments": [
      { "nosso_numero": "00012350", "prepayment_amount": 300.00 }
    ]
  }'

Resposta (201):

{
  "status": "prepaid",
  "message": "Installment prepaid successfully"
}

📘

Quitação total

Se o total_prepayment_amount cobre o saldo remanescente da operação, ela é marcada como liquidada — todas as parcelas restantes recebem baixa e a operação sai da carteira ativa.

5.3 Receber webhooks de confirmação

Após processar a baixa, a IORQ envia um webhook LOAN_UPDATE para o endpoint registrado. O tipo de mudança vem no campo data.status:

Exemplo de webhook recebido (o corpo do POST é o objeto payload):

{
  "event": "update",
  "data": {
    "entity_id": "OP-001",
    "status": "settled_installment",
    "nosso_numero": "00012345",
    "installment_code": "1"
  }
}

📘

Modelo de eventos

A IORQ envia um único tipo de mensagem (LOAN_UPDATE); o discriminador é data.status. Ver o Catálogo de eventos para todos os valores possíveis.

6. Estados da parcela

stateDiagram-v2
    [*] --> active: Operação ativa
    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
    settled --> [*]
    prepaid --> [*]

Os estados reais da parcela (InstallmentStates) incluem active, late, paid, paid_late, partially_paid, prepaid, settled (entre outros de processamento com a administradora). A IORQ atualiza estados automaticamente conforme recebe as notificações e o ciclo da operação avança.

7. Cenários de erro

8. Próximos fluxos

Operações que não seguem o caminho de liquidação normal entram em outros fluxos: