Portabilidade + Refinanciamento

Fluxo de compra de dívida de consignado militar (Exército) via assinatura em lote. A QI Tech emite uma CCB de quitação (debt_purchase) que paga o banco vendedor, uma CCB de portabilidade (portability) que porta o contrato, e um refinancing consolidador sempre obrigatório que carrega seguro e troco. Tudo assinado uma única vez via QI Sign.

Contas por operação

Cada operação do fluxo exige uma conta de desembolso distinta:

debt_purchase → conta interna QI em nome do tomador. O desembolso cai nessa conta e quita a dívida origem no banco vendedor via after_disbursement_actions (boleto/PIX).
refinancing → conta externa do tomador. O troco do refinanciamento é desembolsado nessa conta.

O parceiro abre a conta interna via POST /account antes da emissão. Ver Conta Interna para Desembolso.

Cenários

O refinancing consolidador é sempre obrigatório no batch militar — é ele quem carrega seguro e troco.

Cenário	Composição	Quando usar
α	1× `debt_purchase` + 1× `portability` + 1× `refinancing`	Porta uma dívida externa
β	N× `debt_purchase` + N× `portability` + 1× `refinancing`	Porta N dívidas externas num único envelope
γ	α ou β + `financial.rebates` no `refinancing`	Qualquer composição acima com prêmio de seguro — gera `insurance_premium_term` automaticamente

Regra do seguro e do troco

Seguro (financial.rebates com fee_type: "insurance_premium_qi") e troco só podem ser enviados no refinancing consolidador (Passo 6).

debt_purchase — rebates proibido (CCB de quitação não carrega seguro).
portability — rebates proibido e final_disbursement_amount deve ser 0.

Sequência de chamadas

 POST /debt_simulation  (opcional — condições do refinanciamento consolidado)

 POST /upload   (documentos do tomador)
    └─ (opcional) POST /upload  (documento de identificação do tomador)

 POST /account  (conta interna QI p/ debt_purchase)

 POST /document/document_batch      → criar envelope de assinatura
    └─ (opcional) personal_document com as chaves do documento de identificação

 POST /debt  (debt_purchase)        → desembolso em conta interna QI

 POST /debt  (portability)          → sem troco, sem seguro

 POST /debt  (refinancing)          → seguro + troco em conta externa

 PUT  /document/document_batch/{key}/send_to_signature

Ordem obrigatória de inserção no batch

debt_purchase deve ser inserido antes da portability que o referencia, e a portability antes do refinancing consolidador. Inverter a ordem dispara:

DOC000110 (HTTP 422) — portability cujo refinanced_credit_operations[].operation_key não casa com nenhum debt_purchase já inserido no batch.
DOC000112 (HTTP 422) — refinancing cujo refinanced_credit_operations[].operation_key não casa com nenhuma portability já inserida no batch.

0. Simulação (opcional)

Antes de abrir o lote é possível simular as condições da operação consolidada — parcela, prazo, IOF, CET e troco — sem criar nada. A simulação é uma só, feita sobre o refinancing consolidador: as dívidas portadas entram como itens de refinanced_credit_operations. Não se simula debt_purchase nem portability separadamente.

ENDPOINT

/debt_simulation

MÉTODO

POST

Como a dívida portada entra na simulação

Cada item de refinanced_credit_operations pode ser informado de duas formas:

Dívida externa (ainda não existe na QI Tech) — informe due_balance com o saldo devedor do contrato no banco vendedor. Opcionalmente envie também monthly_interest_rate e disbursement_date da operação de origem: com esses dois campos a QI Tech corrige o saldo até a data de desembolso da nova operação; sem eles, o due_balance é usado exatamente como enviado.
Operação QI ativa (refinanciamento puro) — informe credit_operation_key. O saldo devedor é calculado pela QI Tech.

Request Body

Dívida externa (port + refin)
Operação QI ativa (refin puro)
Simulando pelo troco desejado

{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    {
      "due_balance": 8500.00,
      "monthly_interest_rate": 0.0225,
      "disbursement_date": "2024-03-15",
      "original_deadline": 60
    }
  ]
}

{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    { "credit_operation_key": "<key da operação QI a refinanciar>" }
  ]
}

{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "final_disbursement_amount": 2000.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    {
      "due_balance": 8500.00,
      "monthly_interest_rate": 0.0225,
      "disbursement_date": "2024-03-15"
    }
  ]
}

Campos chave

Campo	Descrição
`collaterals[].collateral_type`	`military_payroll` (obrigatório)
`collaterals[].collateral_data.reservation_type`	`refinancing` — a simulação representa o consolidador, mesmo quando há portabilidade de dívida externa
`collaterals[].collateral_data.registration_code`	Matrícula do militar no Zetra
`refinanced_credit_operations[].due_balance`	Saldo devedor da dívida portada. Obrigatório quando a dívida é externa (não existe `credit_operation_key`)
`refinanced_credit_operations[].monthly_interest_rate`	Taxa mensal do contrato de origem — usada, junto com `disbursement_date`, para corrigir o `due_balance` até o desembolso da nova operação
`refinanced_credit_operations[].disbursement_date`	Data de desembolso do contrato de origem
`refinanced_credit_operations[].original_deadline`	Prazo original do contrato de origem (informativo)
`refinanced_credit_operations[].credit_operation_key`	Chave da operação QI a refinanciar — alternativa ao `due_balance`
`financial.installment_face_value`	Parcela desejada — ≤ `balance` retornado na Consulta de Margem
`financial.final_disbursement_amount`	Troco desejado. Alternativa ao `installment_face_value`: o valor financiado vira `soma dos due_balance + troco`
`financial.number_of_installments`	Prazo — ∈ `allowed_installment_numbers`

Cenário β (N dívidas portadas)

Para simular a portabilidade de N dívidas externas num único envelope, envie N itens em refinanced_credit_operations, cada um com seu due_balance. A simulação devolve as condições do consolidador que quita todas elas.

Diferenças em relação à emissão

modality.code não é necessário na simulação — só na emissão (POST /debt) da portability e do refinancing.
Não é preciso enviar document_batch_key, disbursement_bank_account, purchaser_document_number nem os dados cadastrais completos do tomador: na simulação o borrower se resume a person_type + individual_document_number.
portability_data (com origin_econsig_id e token) também não entra na simulação — é exigido só na emissão da portability.

Response

Síncrona — retorna disbursement_options[] com cronograma de parcelas, IOF, CET e, quando há refinanciamento, o due_balance corrigido de cada dívida portada.

1. Upload dos documentos

Antes de abrir a conta e o lote, faça o upload dos documentos exigidos na operação via POST /upload. Cada chamada retorna um document_key, identificador do documento referenciado nas etapas seguintes.

ENDPOINT

/upload

MÉTODO

POST

→ Autenticação, headers, FormData e exemplos de código (Python / Node.js) em Upload de Documentos.

Atenção

Salve o document_key retornado — ele é necessário para a consulta e o uso futuro do documento.

(Opcional) Documento de identificação do tomador

Se o seu fluxo já coleta o documento de identificação do tomador (registro militar, RG, CNH etc.), suba os arquivos neste mesmo passo e informe as chaves na abertura do lote (Passo 3). A etapa de captura do documento chega pré-atendida na jornada de assinatura e o tomador não precisa fotografar o documento novamente.

Suba um arquivo por lado do documento, ou um arquivo único no caso de documento digital. Não é preciso classificar o arquivo no upload: é o campo em que você informa a chave, no Passo 3, que declara qual lado ela representa.

Campo do `personal_document`	Arquivo esperado
`document_identification_front_key`	Frente do documento de identificação
`document_identification_back_key`	Verso do documento de identificação
`document_identification_full_key`	Documento digital completo, em arquivo único

Tipos aceitos e os modos de envio de cada um:

`type`	Documento	Frente e verso	Arquivo único
`military_registry`	Registro militar	✔	—
`rg`	Registro Geral (RG)	✔	—
`cnh`	Carteira Nacional de Habilitação	✔	✔
`cin`	Carteira de Identidade Nacional	—	✔

O conjunto efetivamente aceito também depende da jornada de assinatura configurada para o seu requester — um type fora dessa configuração retorna DOC000130.

Atenção

Esses arquivos ficam vinculados ao lote, mas não são assinados: não entram no envelope como documentos assináveis e não participam do send_to_signature.

2. Abrir a conta interna em nome do tomador

Em compra de dívida, portabilidade e refinanciamento do consignado militar (Exército), o desembolso da operação não vai direto para a conta externa do tomador: ele cai numa conta interna em nome do tomador (aberta pelo parceiro via POST /account). É a partir dessa conta que a QI executa as ações pós-desembolso — quitação do contrato externo, repasse de troco, conciliação.

ENDPOINT

/account

MÉTODO

POST

A conta é aberta pelo parceiro (autenticado com seus client_integration_key), com account_owner.individual_document_number apontando para o CPF do militar tomador. Reutilize a conta existente — uma por tomador (não abra uma nova a cada operação).

O campo account_owner.document_identification recebe o document_key retornado no Passo 1 (upload do documento de identificação do tomador).

Request Body

{
  "account_owner": {
    "person_type": "natural",
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "individual_document_number": "<CPF DO MILITAR>",
    "mother_name": "MARIA DA SILVA",
    "birth_date": "1985-03-12",
    "is_pep": false,
    "document_identification": "<document_key DO PASSO 1>",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "900000000"
    },
    "address": {
      "street": "Eixo Monumental",
      "state": "DF",
      "city": "Brasília",
      "neighborhood": "Asa Sul",
      "number": "215",
      "postal_code": "70000000"
    }
  }
}

Campos chave

Campo	Tipo	Descrição
`account_owner.person_type`	string	Fixo: `natural` (pessoa física)
`account_owner.individual_document_number`	string	CPF do militar tomador
`account_owner.document_identification`	string (UUID)	`document_key` do documento enviado no Passo 1
`account_owner.is_pep`	boolean	Indica se o tomador é pessoa politicamente exposta

Response Body

{
  "account_key": "1167955-...",
  "account_branch": "0001",
  "account_number": "1167955",
  "account_digit": "1",
  "owner_document_number": "<CPF DO MILITAR>",
  "owner_name": "<NOME DO MILITAR>",
  "bank_code": "329",
  "account_status": "active"
}

Idempotência por tomador

Se já existe conta ativa para esse owner_document_number no parceiro, evite chamar POST /account de novo — consulte GET /accounts?owner_document_number=<CPF> antes e reaproveite o account_key retornado.

3. Abrir o lote

ENDPOINT

/document/document_batch

MÉTODO

POST

Request Body

{
  "type": "military_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote EB portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>"
}

Campos chave

Campo	Tipo	Descrição
`type`	string	Fixo: `military_payroll_external_batch`
`certifier_type`	string	Fixo: `qi_sign`
`batch_name`	string	Nome identificador do lote — único (não reutilize entre lotes) e máximo 100 caracteres
`request_control_key`	string (UUIDv4)	Idempotência — não reutilize entre lotes
`personal_document`	object	(Opcional) Chaves do documento de identificação do tomador subido no Passo 1

(Opcional) Enviar o documento de identificação pré-coletado

Informe as document_key do Passo 1 no objeto personal_document, na raiz do payload de abertura do lote:

Request Body com documento pré-coletado

{
  "type": "military_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote EB portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>",
  "personal_document": {
    "type": "military_registry",
    "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
    "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
  }
}

Campo	Tipo	Descrição
`personal_document.type`	string	Tipo do documento: `military_registry`, `rg`, `cnh` ou `cin`
`personal_document.document_identification_front_key`	string (UUIDv4)	Chave da frente — obrigatório junto com `..._back_key`
`personal_document.document_identification_back_key`	string (UUIDv4)	Chave do verso — obrigatório junto com `..._front_key`
`personal_document.document_identification_full_key`	string (UUIDv4)	Chave do arquivo único (documento digital) — não combinar com frente e verso

Regras

Envie frente + verso ou o arquivo único — nunca os dois modos juntos. Combinação inválida retorna DOC000128.
Os arquivos devem pertencer ao seu requester e já ter o upload concluído — chave inexistente ou de outro requester retorna DOC000004; arquivo ausente retorna DOC000049.
Cada arquivo só pode ser usado em um lote; reaproveitar uma chave já vinculada retorna DOC000137.
O envio ocorre apenas na abertura do lote — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, nenhum lote é criado.
A requisição precisa identificar o titular dos arquivos: envie o header SELECTED-AGENT. Sem ele, a abertura retorna QIT000004.

Response Body

{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}

Guarde o document_batch_key retornado — ele é referenciado em todas as chamadas seguintes.

→ Para consultar, limpar documentos ou conferir o batch antes do envio, ver Assinatura em Lote.

4. Emitir `debt_purchase`

CCB de quitação da dívida original. A QI Tech vai pagar o banco vendedor.

ENDPOINT

/debt

MÉTODO

POST

Particularidades do debt_purchase

document_batch_key incluído na raiz do payload (mesmo nível de borrower, financial).
disbursement_bank_account aponta para a conta interna QI do tomador (criada no Passo 2).
collaterals vazio — o debt_purchase é a operação-ponte que carrega o saldo externo; não leva colateral.
after_disbursement_actions na raiz define a quitação automática da dívida origem após o desembolso (boleto ou PIX do banco vendedor).

Request Body

{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "055" },
    "is_pep": false,
    "address": {
      "city": "Brasília",
      "state": "DF",
      "number": "215",
      "street": "Eixo Monumental",
      "complement": "",
      "postal_code": "70000000",
      "neighborhood": "Asa Sul"
    },
    "role_type": "issuer",
    "birth_date": "1985-03-12",
    "mother_name": "MARIA DA SILVA",
    "nationality": "Brasileiro",
    "person_type": "natural",
    "marital_status": "single",
    "individual_document_number": "45507529710",
    "gender": "male",
    "document_identification_type": "rg",
    "document_identification_number": "1234567",
    "document_identification_date": "2015-01-01"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 100,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [],
  "requester_identifier_key": "<UUIDv4 gerado por request>",
  "disbursement_bank_account": {
    "bank_code": "329",
    "account_digit": "1",
    "branch_number": "0001",
    "account_number": "1167955",
    "document_number": "45507529710",
    "name": "JOÃO DA SILVA"
  },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}

Campos que devem ser alterados

Campo	Obrigatório alterar?	Observação
`document_batch_key`	✅ Sim	Valor retornado no Passo 3
`borrower.*`	✅ Sim	Dados reais do tomador
`financial.first_due_date` / `disbursement_date`	✅ Sim	Conforme calendário da operação
`financial.installment_face_value` / `number_of_installments` / `monthly_interest_rate`	✅ Sim	Conforme condições comerciais
`purchaser_document_number`	✅ Sim	CNPJ do comprador (via variável de ambiente)
`requester_identifier_key`	✅ Sim	UUIDv4 único por requisição
`disbursement_bank_account`	✅ Sim	Conta interna QI em nome do tomador (Passo 2). O `account_branch` da resposta do `POST /account` vai no campo `branch_number`
`after_disbursement_actions`	✅ Sim	Quitação da dívida origem. `action_type`: `bankslip_payment` (boleto) ou PIX. Preencha `digitable_line` (boleto) ou `qr_code` (PIX) do banco vendedor

Response Body

{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação debt_purchase>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}

Guarde a key retornada — ela é passada em refinanced_credit_operations[].operation_key da portability correspondente.

5. Emitir `portability`

CCB de portabilidade da dívida. Cada portabilidade referencia exatamente um debt_purchase via refinanced_credit_operations. Não carrega seguro nem troco — ambos vão no refinancing consolidador.

ENDPOINT

/debt

MÉTODO

POST

Particularidades da portability

collaterals[0].collateral_type é military_payroll com reservation_type: "portability".
collaterals[0].collateral_data.portability_data é obrigatório — contém o origin_econsig_id (contrato de origem no Zetra) e o token do militar.
refinanced_credit_operations carrega a key do debt_purchase correspondente.
modality.code "0202" é obrigatório em portabilidade/refinanciamento do Exército.

Portabilidade sem seguro e sem troco

Em batch militar, a portability não pode carregar financial.rebates (seguro). O seguro é enviado exclusivamente no refinancing consolidador. A QI Tech rejeita o POST /debt que violar essa regra.

Request Body

{
  "borrower": { "...": "mesmo borrower do Passo 4" },
  "financial": {
    "first_due_date": "2026-07-01",
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "final_disbursement_amount": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "portability",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678",
        "portability_data": {
          "origin_econsig_id": "2016587",
          "token": "12345678"
        }
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "mesma conta interna do Passo 4" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key DO PASSO 4>" }
  ]
}

Campos que devem ser alterados

Campo	Obrigatório alterar?	Observação
`document_batch_key`	✅ Sim	Valor retornado no Passo 3
`refinanced_credit_operations[0].operation_key`	✅ Sim	`key` do `debt_purchase` referenciado (Passo 4)
`collaterals[0].collateral_data.registration_code`	✅ Sim	Matrícula do militar no Zetra
`collaterals[0].collateral_data.token`	✅ Sim	Token Zetra do militar
`collaterals[0].collateral_data.portability_data.origin_econsig_id`	✅ Sim	ID do contrato de origem no Zetra (e-consignado da instituição vendedora)
`collaterals[0].collateral_data.portability_data.token`	✅ Sim	Token Zetra do militar
`modality.code`	🚫 Fixo	Sempre `"0202"` em portabilidade/refinanciamento do Exército
`financial.installment_face_value`	🚫 Não enviar	Valor da parcela (auto calculado)
`financial.rebates`	🚫 Proibido	Seguro não é aceito em portabilidade — só no `refinancing`

Response Body

{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação portability>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}

Guarde a key desta portabilidade — usada em refinanced_credit_operations do refinancing consolidador (Passo 6).

Erros possíveis na criação

Código	HTTP	Quando
`DOC000110`	422	`refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de `debt_purchase` já inserido no batch
`DOC000114`	422	`refinanced_credit_operations[].operation_key` já está em outra portabilidade do mesmo batch (duplicidade)
`COP000515`	400	`final_disbursement_amount` ≠ `0` — portabilidade não carrega troco
`COP000516`	400	`financial.rebates` presente — portabilidade não aceita seguro
`INVALID_MODALITY_CODE`	400	portabilidade sem `modality.code: "0202"`

6. Emitir `refinancing` consolidador

CCB mãe que consolida as portabilidades num único instrumento. Sempre obrigatória no batch militar — tanto no cenário α (1 portabilidade) quanto no β (N portabilidades). É a única operação do fluxo que carrega seguro e troco.

ENDPOINT

/debt

MÉTODO

POST

Particularidades do refinancing consolidador

collaterals[0].collateral_type é military_payroll com reservation_type: "refinancing".
refinanced_credit_operations lista as key de todas as portabilidades do batch.
disbursement_bank_account aponta para a conta externa do tomador — destino do troco.
modality.code "0202" é obrigatório.
financial.rebates é opcional — único lugar do fluxo que aceita seguro.
after_disbursement_actions só é enviado quando há seguro — liquida o prêmio após o desembolso.

after_disbursement_actions exige seguro

after_disbursement_actions só pode ser enviado no refinancing quando a operação tem seguro (financial.rebates presente). Enviar after_disbursement_actions sem rebates faz a QI Tech rejeitar o POST /debt.

Request Body

Sem seguro
Com seguro + troco (Cenário γ)

{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 1000,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ]
}

{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 1500,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "rebates": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "credit_insurance_blindado"
      }
    ]
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ],
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}

Campos que devem ser alterados

Campo	Obrigatório alterar?	Observação
`document_batch_key`	✅ Sim	Valor retornado no Passo 3
`refinanced_credit_operations`	✅ Sim	Todas as `key` das portabilidades emitidas no Passo 5
`collaterals[0].collateral_data.registration_code`	✅ Sim	Matrícula do militar no Zetra
`collaterals[0].collateral_data.token`	✅ Sim	Token Zetra do militar
`reservation_method`	✅ Sim	Sempre `"issuing"` para o consolidador
`modality.code`	🚫 Fixo	Sempre `"0202"`
`disbursement_bank_account`	✅ Sim	Conta externa do tomador — destino do troco
`financial.rebates`	⚠️ Opcional	Único lugar do fluxo que aceita seguro. Incluir `[{ "fee_type": "insurance_premium_qi", ... }]` apenas se a operação tem seguro
`financial.final_disbursement_amount`	🚫 Não enviar	Valor final do desembolso (troco) calculado automaticamente baseado no valor da parcela
`after_disbursement_actions`	⚠️ Só com seguro	Liquida o prêmio do seguro após desembolso. Só envie quando `rebates` está presente — caso contrário a QI Tech rejeita o `POST /debt`

Erros possíveis na criação

Código	HTTP	Quando
`DOC000109`	422	Batch já contém outro `refinancing` — só 1 por batch
`DOC000112`	422	`refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de portabilidade no batch
`COP000517`	400	`refinancing` com seguro (`rebates`) sem nenhuma `after_disbursement_actions` — seguro exige ao menos uma ação pós-desembolso
`COP000518`	400	`refinancing` sem seguro carregando `after_disbursement_actions` — só permitido quando há `rebates`
`INVALID_MODALITY_CODE`	400	refinanciamento sem `modality.code: "0202"`

7. Enviar para assinatura

Fecha o lote e dispara os documentos para o QI Sign. Antes desse PUT, nada é enviado ao militar.

ENDPOINT

/document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature

MÉTODO

PUT

Body: {}. Response: HTTP 200.

Erros possíveis no envio

Código	HTTP	Quando
`DOC000108`	422	Batch contém mais de 1 `insurance_premium_term`
`DOC000109`	422	Batch contém mais de 1 `refinancing`
`DOC000110`	422	`portability` cujo `refinanced_op` não casa com nenhum `debt_purchase` no batch
`DOC000111`	422	Batch sem `refinancing` consolidador
`DOC000114`	422	`debt_purchase` referenciado por 0 ou mais de 1 portabilidade

Conferir antes de enviar

Use GET /document/document_batch/DOCUMENT_BATCH_KEY para listar os documentos agrupados e confirmar a composição antes do send_to_signature. Ver Assinatura em Lote.

→ Próximo passo: Formalização

Mapa consolidado de erros

Código	HTTP	Ponto de disparo	Quando
`DOC000108`	422	criação + envio	Mais de 1 `insurance_premium_term` no batch
`DOC000109`	422	criação + envio	Mais de 1 `refinancing` no batch
`DOC000110`	422	criação + envio	`portability` com `refinanced_op` sem `debt_purchase` casado no batch
`DOC000111`	422	envio	Batch sem `refinancing` consolidador
`DOC000112`	422	criação	`refinancing` com `refinanced_op` sem portabilidade casada no batch
`DOC000114`	422	criação + envio	`debt_purchase` referenciado por ≠ 1 portabilidade (0 órfão ou ≥ 2 duplicado)
`COP000515`	400	criação (`portability`)	`final_disbursement_amount` ≠ `0` na portabilidade
`COP000516`	400	criação (`portability`)	`financial.rebates` enviado na portabilidade
`COP000517`	400	criação (`refinancing`)	`refinancing` com seguro sem nenhuma `after_disbursement_actions`
`COP000518`	400	criação (`refinancing`)	`refinancing` sem seguro carregando `after_disbursement_actions`
`INVALID_MODALITY_CODE`	400	criação (`portability`/`refinancing`)	operação sem `modality.code: "0202"`
`DOC000128`	400	abertura do lote	`type` do `personal_document` não suporta o modo enviado (frente e verso × arquivo único)
`DOC000129`	400	abertura do lote	Jornada configurada para o requester não coleta documento de identificação
`DOC000130`	400	abertura do lote	`type` do `personal_document` fora dos tipos aceitos pela configuração do requester
`DOC000137`	400	abertura do lote	`document_key` do documento de identificação já vinculada a outro lote
`DOC000004`	404	abertura do lote	`document_key` do documento de identificação não encontrada (inclui arquivo de outro requester)
`DOC000049`	400	abertura do lote	Documento de identificação sem arquivo — upload não concluído
`QIT000004`	403	abertura do lote	`personal_document` enviado sem o header `SELECTED-AGENT`

Notas sobre erros recorrentes

DOC000110 dispara em dois momentos: na criação da portabilidade (validação imediata) e no envio (cobertura defensiva).
DOC000114 dispara em dois momentos: na criação da segunda portabilidade duplicada e no envio (cobre o debt_purchase órfão, i.e. count = 0).
DOC000111 dispara apenas no envio — não há validação na criação.
Batches que não são military_payroll_external_batch não disparam nenhuma das validações acima.

Glossário

Termo	Significado
CCB	Cédula de Crédito Bancário — instrumento de dívida emitido pelo banco
Zetra	Sistema de gestão do e-consignado militar (Exército) — onde a reserva de margem é averbada
matrícula militar	`registration_code` — identificador do militar no Zetra
token	Token Zetra do militar — autoriza a operação de consignado (6 a 8 caracteres)
portability_data	Dados do contrato de origem no Zetra (`origin_econsig_id`, `token`) da instituição vendedora
origin_econsig_id	ID do e-consignado de origem no Zetra — o contrato externo que está sendo portado
modality.code	Código de modalidade do consignado militar — `"0202"` para portabilidade/refinanciamento
credit_operation_key	Chave única da operação retornada por `POST /debt` — também chamada `key`
insurance_premium_term	Documento extra gerado automaticamente no batch quando uma `portability` ou `refinancing` carrega `financial.rebates` com `fee_type: "insurance_premium_qi"`. Nunca originado de `debt_purchase`
QI Sign	Provedor de assinatura digital QI Tech (configurado via `certifier_type: "qi_sign"`)

Cenários​

Sequência de chamadas​

0. Simulação (opcional)​

Campos chave​

Response​

1. Upload dos documentos​

(Opcional) Documento de identificação do tomador​

2. Abrir a conta interna em nome do tomador​

Campos chave​

3. Abrir o lote​

Campos chave​

(Opcional) Enviar o documento de identificação pré-coletado​

4. Emitir debt_purchase​

Campos que devem ser alterados​

5. Emitir portability​

Campos que devem ser alterados​

Erros possíveis na criação​

6. Emitir refinancing consolidador​

Campos que devem ser alterados​

Erros possíveis na criação​

7. Enviar para assinatura​

Erros possíveis no envio​

Mapa consolidado de erros​

Glossário​

Cenários

Sequência de chamadas

0. Simulação (opcional)

Campos chave

Response

1. Upload dos documentos

(Opcional) Documento de identificação do tomador

2. Abrir a conta interna em nome do tomador

Campos chave

3. Abrir o lote

Campos chave

(Opcional) Enviar o documento de identificação pré-coletado

4. Emitir `debt_purchase`

Campos que devem ser alterados

5. Emitir `portability`

Campos que devem ser alterados

Erros possíveis na criação

6. Emitir `refinancing` consolidador

Campos que devem ser alterados

Erros possíveis na criação

7. Enviar para assinatura

Erros possíveis no envio

Mapa consolidado de erros

Glossário