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.

Uma chamada cobre até 20 operações, cada uma com N parcelas, e cada operação leva o PDF do aditamento que respalda a mudança. O aditamento fica anexado à operação na IORQ, ao lado da CCB, e segue para a administradora.

📘

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 operação e por parcela no corpo: as novas datas já estão persistidas 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

🚧

A janela é ancorada na data de aquisição, não na atual

A curva de valorização do ativo parte da data com que a parcela entrou na carteira. Por isso o limite não acompanha a parcela quando ela se move: depois de adiar uma parcela em 20 dias, restam 6 — não outros 26.

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.

As parcelas de todas as operações da chamada seguem para a administradora em uma única remessa, reagrupadas por operação do lado de lá.

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 (até 20 operações + aditamentos)
    IORQ->>IORQ: Valida TODAS as operações e os arquivos
    IORQ->>IORQ: Persiste as novas datas
    IORQ->>IORQ: Anexa o aditamento de cada operação
    IORQ-->>INT: 200 — resultado por operação e parcela
    IORQ->>ADM: Uma remessa de alteração de vencimento
    opt Cobrança sob responsabilidade da IORQ
        IORQ->>BANK: Atualiza vencimento dos boletos
        BANK-->>IORQ: Boletos atualizados
        IORQ->>INT: Webhook LOAN_UPDATE (status: due_date_changed, um por parcela)
    end

4. Passo a passo

PATCH /api/installment/due-date · multipart/form-data

Campos de due_date_change_data

O FIDC da operação vem do header iorq-fund-id — não há campo de fundo no corpo.

Exemplo — mover duas parcelas de OP-001 e uma de CCB-889912, cada uma com o seu aditamento:

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' \
  -F 'due_date_change_data={
    "loans": [
      {
        "originator_proposal_code": "OP-001",
        "document": "aditamento-OP-001",
        "installments": [
          { "code": "5", "due_date": "2026-08-25" },
          { "code": "6", "due_date": "2026-09-25" }
        ]
      },
      {
        "banker_proposal_code": "CCB-889912",
        "document": "aditamento-CCB-889912",
        "installments": [
          { "code": "2", "due_date": "2026-08-28" }
        ]
      }
    ]
  }' \
  -F '[email protected];type=application/pdf' \
  -F '[email protected];type=application/pdf'

Resposta (200):

{
  "loans": [
    {
      "id_loan": "0d3a2f7e-5c1b-4c8e-9f4a-2b7d6e1a9c33",
      "originator_proposal_code": "OP-001",
      "banker_proposal_code": "CCB-100045",
      "installments": [
        {
          "id_installment": "9b1f6c2a-8d34-4e0b-a1c5-7f2e9d4b6a18",
          "code": "5",
          "previous_due_date": "2026-08-15",
          "new_due_date": "2026-08-25",
          "changed": true
        },
        {
          "id_installment": "4c8a1d7f-2e6b-49c0-b3a9-5d1f8e7c2b64",
          "code": "6",
          "previous_due_date": "2026-09-25",
          "new_due_date": "2026-09-25",
          "changed": false
        }
      ]
    },
    {
      "id_loan": "7f2c9a41-3b8e-4d05-9c1a-6e4b2d8f0a57",
      "originator_proposal_code": "OP-014",
      "banker_proposal_code": "CCB-889912",
      "installments": [
        {
          "id_installment": "b3d5e9c1-7a24-4f68-8e0b-1c9a5d3f7b42",
          "code": "2",
          "previous_due_date": "2026-08-10",
          "new_due_date": "2026-08-28",
          "changed": true
        }
      ]
    }
  ]
}

As operações voltam na ordem em que foram pedidas, e cada uma traz os dois identificadores resolvidos — útil quando você enviou só um deles.

📘

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 muda 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, de qualquer operação da chamada. 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-100045",
    "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, e isso vale entre operações: se uma parcela da última operação do payload falhar uma regra, nenhuma data é alterada em nenhuma operação, nenhum aditamento é anexado e nada é propagado. Uma chamada com 20 operações ou é aplicada inteira ou não é aplicada.

🚧

Lote grande, rejeição inteira

Em cargas grandes isso significa que um único identificador errado devolve 404 para o lote todo. Se você monta o payload a partir de uma planilha, vale validar os identificadores antes de enviar — ou quebrar o envio em lotes menores, que falham de forma mais isolada.

7. Próximos fluxos