Alteração de vencimento

PATCH /api/installment/due-date

1. Quando usar este fluxo

Use quando uma parcela em aberto precisar mudar apenas a data de vencimento — negociação pontual com o tomador, ajuste para dia útil, feriado local. A operação continua na carteira, os valores não mudam e nenhum estado transiciona. Não confunda com renegociação (que baixa o contrato e cede um novo) nem com recompra (que tira o ativo da carteira) — para essas, veja Operações pós-cessão.

📘

Síncrona, ao contrário do resto da API

Todos os demais endpoints operacionais respondem 201 e entregam o resultado via webhook. Este responde 200 com o resultado por parcela no corpo: a nova data já está persistida na IORQ quando a resposta chega. O que resta assíncrono é a propagação, que depende de quem cuida da cobrança da operação: o registro na administradora acontece sempre; o boleto só é atualizado quando a cobrança é de responsabilidade da IORQ — e, nesse caso, a chegada do boleto atualizado é confirmada pelo webhook due_date_changed.

2. Regras de validação

3. Fluxo end-to-end

A propagação depende de quem é responsável pela cobrança da operação: se a cobrança é da IORQ, o boleto é atualizado no bancarizador e a ocorrência segue para a administradora; se a cobrança não é da IORQ, a alteração é registrada apenas na administradora.

sequenceDiagram
    participant INT as Integrador
    participant IORQ as IORQ
    participant BANK as Bancarizador (boleto)
    participant ADM as Administradora

    INT->>IORQ: PATCH /api/installment/due-date
    IORQ->>IORQ: Valida e persiste as novas datas
    IORQ-->>INT: 200 — resultado por parcela
    IORQ->>ADM: Ocorrência de alteração de vencimento
    opt Cobrança sob responsabilidade da IORQ
        IORQ->>BANK: Atualiza vencimento do boleto
        BANK-->>IORQ: Boleto atualizado
        IORQ->>INT: Webhook LOAN_UPDATE (status: due_date_changed, um por parcela)
    end

4. Passo a passo

PATCH /api/installment/due-date · application/json

Campos do payload

Exemplo — mover a parcela 5 de 15/08 para 25/08:

curl -X PATCH 'https://hs-receiver-app-production.iorq.com.br/api/installment/due-date' \
  -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",
    "installments": [
      { "code": "5", "due_date": "2026-08-25" }
    ]
  }'

Resposta (200):

{
  "id_loan": "0d3a2f7e-5c1b-4c8e-9f4a-2b7d6e1a9c33",
  "originator_proposal_code": "OP-001",
  "banker_proposal_code": "CCB-889912",
  "installments": [
    {
      "id_installment": "9b1f6c2a-8d34-4e0b-a1c5-7f2e9d4b6a18",
      "code": "5",
      "previous_due_date": "2026-08-15",
      "new_due_date": "2026-08-25",
      "changed": true
    }
  ]
}

📘

changed: false é sucesso

Se a parcela já estava na data pedida, a chamada é um no-op idempotente: a parcela volta com changed: false e nada é propagado para ela. Repetir a mesma chamada inteira é seguro.

5. Webhook de confirmação

Quando a cobrança é de responsabilidade da IORQ, ao entrar em vigor a nova data no boleto do bancarizador a IORQ envia um LOAN_UPDATE com data.status: due_date_changed — um webhook por parcela alterada. A nova data viaja em data.due_date, então não é preciso re-consultar a operação:

{
  "event": "update",
  "data": {
    "entity_id": "OP-001",
    "status": "due_date_changed",
    "nosso_numero": "00012345678",
    "installment_code": "5",
    "banker_proposal_code": "CCB-889912",
    "entity_type": "ccb",
    "due_date": "2026-08-25"
  },
  "iorq_fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36"
}

🚧

A resposta 200 confirma a IORQ; o webhook confirma o boleto

Entre a resposta síncrona e o webhook, a carteira da IORQ já reflete a nova data, mas o boleto do tomador ainda pode exibir a antiga. Se o seu fluxo apresenta o boleto ao tomador, aguarde o due_date_changed antes de comunicar a nova data.

📘

Cobrança fora da IORQ: sem boleto, sem webhook de boleto

Quando a cobrança da operação não é de responsabilidade da IORQ, não há boleto a atualizar — a alteração é registrada apenas na administradora e a resposta síncrona (200) é a confirmação da operação. Não espere um due_date_changed nesse cenário.

6. Erros

A validação é tudo-ou-nada por chamada: se qualquer parcela do payload falhar em uma regra, nenhuma data é alterada.

7. Próximos fluxos