Liquidação

POST /installment/settle · POST /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 reconciliaçã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 /installment/settle
    IORQ-->>INT: 200 OK
    IORQ->>IORQ: Processa baixa + atualiza estoque
    IORQ->>INT: Webhook installment_settled
    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 /installment/settle. Cada chamada registra a liquidação de uma parcela.

POST /installment/settle · application/json

Campos do payload

Exemplo de request:

curl -X POST 'https://hs-api.iorq.com.br/installment/settle' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "originator_proposal_code": "OP-001",
    "installment_code": "1",
    "settled_at": "2026-05-30",
    "settled_value": 280.00,
    "payment_method": "direct_debit",
    "idempotency_key": "OP-001-1"
  }'

Resposta:

{
  "originator_proposal_code": "OP-001",
  "installment_code": "1",
  "status": "settled",
  "settled_at": "2026-05-30",
  "settled_value": 280.00,
  "processed_at": "2026-05-30T14:22:11Z"
}

5.2 Liquidação antecipada

Use POST /installment/prepayment quando o tomador antecipa pagamento — quita uma ou mais parcelas futuras antes do vencimento. A IORQ recalcula juros e identifica automaticamente quais parcelas foram quitadas pelo valor antecipado.

POST /installment/prepayment · application/json

Exemplo de request:

curl -X POST 'https://hs-api.iorq.com.br/installment/prepayment' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "originator_proposal_code": "OP-001",
    "prepayment_value": 1500.00,
    "prepayment_date": "2026-06-15",
    "payment_method": "pix",
    "idempotency_key": "OP-001-PRE-20260615"
  }'

Resposta:

{
  "originator_proposal_code": "OP-001",
  "status": "prepayment_processed",
  "prepayment_value": 1500.00,
  "settled_installments": ["6", "7", "8", "9", "10"],
  "remaining_balance": 320.00,
  "processed_at": "2026-06-15T10:18:45Z"
}

📘

Quitação total

Se o prepayment_value 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 webhook para o endpoint registrado:

Exemplo de webhook:

{
  "event": "installment_settled",
  "originator_proposal_code": "OP-001",
  "installment_code": "1",
  "settled_value": 280.00,
  "timestamp": "2026-05-30T14:22:11Z"
}

6. Estados da parcela

stateDiagram-v2
    [*] --> pending: Operação ativa
    pending --> settled: POST /installment/settle
    pending --> prepaid: POST /installment/prepayment
    pending --> overdue: Vencida sem pagamento
    overdue --> settled: Pagamento com atraso
    settled --> [*]
    prepaid --> [*]

Estados terminais: settled e prepaid. 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: