Portabilidade + Refinanciamento

Fluxo para trazer dívida de outra instituição (portabilidade) ou renegociar uma operação ativa (refinanciamento) no consignado militar. Ambas as modalidades usam reservation_type: refinancing no /debt, com variações no refinanced_credit_operations.

Diferença vs Margem Livre

Margem Livre (new_credit) cria nova dedução em folha. Refinanciamento (refinancing) reaproveita uma reserva existente — seja interna QI (refin puro) ou externa (portabilidade).

Quando usar cada um

Refinanciamento puro

Cliente já tem operação ativa na QI Tech. Quer renegociar prazo/taxa, eventualmente liberar troco.

• reservation_type: refinancing
• reservation_method: issuing
• refinanced_credit_operations: [{"operation_key": "<UUID da CO QI original>"}]
• modality.code: "0202" (obrigatório)
• Troco (se houver) vai pro borrower via PIX/TED no desembolso

Portabilidade pura

Cliente tem dívida em outro banco. Quer migrar pra QI sem liberar valor adicional.

• reservation_type: refinancing (mesmo enum)
• reservation_method: issuing
• refinanced_credit_operations[]: referencia o contrato externo com original_contract_number + original_financial_institution_document_number + due_balance + original_deadline
• modality.code: "0202"
• Saldo devedor externo é quitado via operação-ponte (QI orquestra internamente)

Compra-de-dívida (com troco)

Cliente tem dívida em outro banco e quer liberar troco. É a combinação dos dois acima.

A QI implementa via compra-de-dívida operacional (sem CTC, que só existe pra INSS):

1. QI emite operação-ponte e desembolsa numa conta aberta pro borrower.
2. Saldo cobre o due_balance da operação externa.
3. QI quita externamente (PIX/TED pro banco original).
4. Margem é liberada no Zetra (via desaverbação da operação antiga).
5. QI averba a operação consignada nova.
6. final_disbursement_amount na simulação é o troco que volta pro cliente.

Pra Exército, a integração é uma só chamada de /debt bem montada — a QI orquestra o resto internamente.

Pré-requisitos

• balance_key recebido na Consulta de Margem.
• Para refinanciamento puro: operation_key da CO QI original.
• Para portabilidade: original_contract_number + original_financial_institution_document_number + due_balance + original_deadline do contrato externo.

1. Simulação

ENDPOINT

/debt_simulation

MÉTODO

POST

Request Body — Refinanciamento puro

{
  "borrower": { "person_type": "natural", "individual_document_number": "45507529710" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 400.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 36,
    "monthly_interest_rate": 0.0195,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "collaterals": [{
    "collateral_type": "military_payroll",
    "percentage": 1,
    "collateral_data": {
      "reservation_type": "refinancing",
      "registration_code": "146254221",
      "refinanced_credit_operations": [
        { "operation_key": "9c8e7d6b-..." }
      ]
    }
  }],
  "modality": { "code": "0202" }
}

Request Body — Portabilidade / Compra-de-dívida

{
  "borrower": { "person_type": "natural", "individual_document_number": "45507529710" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 480.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 48,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "collaterals": [{
    "collateral_type": "military_payroll",
    "percentage": 1,
    "collateral_data": {
      "reservation_type": "refinancing",
      "registration_code": "146254221",
      "refinanced_credit_operations": [{
        "original_contract_number": "00498765/BR",
        "original_financial_institution_document_number": "00000000000191",
        "due_balance": 12500.00,
        "original_deadline": "2027-08-15"
      }]
    }
  }],
  "modality": { "code": "0202" }
}

Campos chave

Campo	Descrição
collaterals[].collateral_data.reservation_type	refinancing (refin + port)
refinanced_credit_operations[].operation_key	UUID da CO QI original (refin puro)
refinanced_credit_operations[].original_contract_number	Contrato externo (portabilidade)
refinanced_credit_operations[].original_financial_institution_document_number	CNPJ banco origem (portabilidade)
refinanced_credit_operations[].due_balance	Saldo devedor externo (portabilidade)
refinanced_credit_operations[].original_deadline	Vencimento original (portabilidade)
modality.code	"0202" (obrigatório em refin/port)

Response

Síncrona. final_disbursement_amount é o troco que vai pro borrower (zero = portabilidade pura sem troco).

2. Emissão

ENDPOINT

/debt

MÉTODO

POST

Mesmo payload da simulação, acrescentando:

• Borrower completo (KYC).
• disbursement_bank_account (pro troco, se houver).
• purchaser_document_number.
• collateral_data.token (token Zetra do militar).

Request Body — Portabilidade completa

{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "address": {
      "city": "São Paulo", "state": "SP", "number": "215",
      "street": "Gilberto Sabino", "complement": "",
      "postal_code": "12345012", "neighborhood": "Pinheiros"
    },
    "role_type": "issuer",
    "birth_date": "1985-03-12",
    "mother_name": "MARIA DA SILVA",
    "person_type": "natural",
    "individual_document_number": "45507529710",
    "gender": "male",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "single"
  },
  "financial": { /* idem simulação */ },
  "collaterals": [{
    "collateral_type": "military_payroll",
    "percentage": 1,
    "collateral_data": {
      "reservation_type": "refinancing",
      "reservation_method": "issuing",
      "registration_code": "146254221",
      "token": "12345678",
      "refinanced_credit_operations": [{
        "original_contract_number": "00498765/BR",
        "original_financial_institution_document_number": "00000000000191",
        "due_balance": 12500.00,
        "original_deadline": "2027-08-15"
      }]
    }
  }],
  "modality": { "code": "0202" },
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "104",
    "account_type": "checking_account",
    "account_digit": "1",
    "branch_number": "3880",
    "account_number": "000736703806",
    "document_number": "45507529710",
    "transfer_method": "pix"
  },
  "purchaser_document_number": "32402502000135"
}

O que acontece após o /debt

Pra portabilidade, a QI executa internamente:

1. Emite a CCB nova → webhook debt (waiting_signature).
2. Aciona o credit-transfer pra quitar o contrato externo → webhook credit_transfer.received_portability quando o banco origem confirma.
3. Aguarda desaverbação do Zetra na operação original → webhook credit_operation.collateral com reservation_status: deleted na operação antiga.
4. Averba a nova operação → webhook credit_operation.collateral com successfully_reserved na operação nova.
5. Desembolsa o troco (se houver) → webhook debt (disbursed).

→ Próximo passo: Formalização

Webhooks específicos de port/refin

Webhook	Quando dispara
credit_transfer.received_portability	Banco origem confirmou portabilidade (port apenas)
credit_transfer_status_change	Atualização credit-transfer (pending → accepted → confirmed)
credit_operation.collateral (reservation_status: deleted)	Desaverbação da operação original confirmada

Falhas específicas

Enumerador	Quando	Ação
origin_contract_not_found	Contrato externo referenciado não existe ou foi quitado	Verificar dados; pode cancelar operação
waiting_for_origin_contract_closure	QI averba só após confirmar quitação do externo	Aguardar (retry automático)
expired_portability	Janela de portabilidade fechou no Zetra	Re-tentar com novo contrato origem
INVALID_MODALITY_CODE	refin/port sem modality.code: "0202"	Adicionar o modality.code

Auto-cancelamento

Operações em status canceled por mais de 7 dias são automaticamente convertidas em canceled_permanently pelo sistema. Aplica-se igualmente a margem livre, refin e port.

→ Cancelamento, Desaverbação e Reversal