Liquidação

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

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 '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",
    "code": "1",
    "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/v2 quando o tomador antecipa pagamento — quita parcelas futuras antes do vencimento. Uma única chamada pode quitar parcelas de uma ou de múltiplas operações (ex.: um único boleto que cobre várias operações). O payload agrupa as operações em loans; cada operação traz suas parcelas antecipadas em prepayment_installments. A IORQ recalcula juros e identifica quais parcelas foram quitadas pelo valor antecipado.

POST /api/installment/prepayment/v2 · application/json

Cada item de loans:

Cada item de prepayment_installments:

Exemplo de request:

curl -X POST 'https://hs-receiver-app-production.iorq.com.br/api/installment/prepayment/v2' \
  -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",
    "due_date": "2026-06-15",
    "total_prepayment_amount": 2800.00,
    "loans": [
      {
        "identifier": { "originator_proposal_code": "OP-001" },
        "code": "PREPAY-001",
        "prepayment_installments": [
          {
            "identifier": { "code": "3" },
            "prepayment_amount": 900.00
          },
          {
            "identifier": { "administrator_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
            "prepayment_amount": 500.00
          }
        ]
      },
      {
        "identifier": { "originator_proposal_code": "OP-002" },
        "code": "PREPAY-002",
        "prepayment_installments": [
          {
            "identifier": { "code": "2" },
            "prepayment_amount": 1400.00
          }
        ]
      }
    ]
  }'

Resposta (201):

{
  "status": "prepaid",
  "message": "Multi-loan prepayment received successfully"
}

📘

Identificação de parcelas na v2

Prefira identifier.code quando você controla o código definido na cessão. Use identifier.administrator_identifier quando tiver o ID da parcela no estoque IORQ (reflexo do identificador da administradora). Pelo menos um dos dois é obrigatório por parcela.

📘

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 com o iorq_fund_id do evento no topo):

{
  "event": "update",
  "data": {
    "entity_id": "OP-001",
    "status": "settled_installment",
    "installment_code": "1"
  },
  "iorq_fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36"
}

📘

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/v2
    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: