Pular para o conteúdo principal

Portabilidade + Refinanciamento

Fluxo para trazer dívida de outra instituição (portabilidade) ou renegociar uma operação ativa (refinanciamento) no consignado militar. Ambas usam reservation_type: refinancing no collateral_data do /debt.

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).

Estrutura do payload

refinanced_credit_operations fica na raiz do payload do /debt, não dentro de collaterals[].collateral_data. Em collateral_data ficam só os dados do colateral militar (registration_code, token, reservation_type, reservation_method).

Quando usar cada um​

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

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

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",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    { "operation_key": "9c8e7d6b-1234-4abc-9def-000000000001" }
  ]
}
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",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    {
      "original_contract_number": "00498765/BR",
      "original_financial_institution_document_number": "00000000000191",
      "due_balance": 12500.00,
      "original_deadline": "2027-08-15"
    }
  ]
}

Campos chave​

CampoLocalizaçãoDescrição
collaterals[].collateral_data.reservation_typedentro do collateralrefinancing (cobre refin + port)
collaterals[].collateral_data.reservation_methoddentro do collateralissuing (averba após formalização) ou creation (averba já no /debt)
collaterals[].collateral_data.registration_codedentro do collateralMatrícula do militar (Zetra)
collaterals[].collateral_data.tokendentro do collateralToken Zetra do militar (obrigatório)
refinanced_credit_operations[].operation_keyraiz do payloadUUID da CO QI original (refin puro / Op A da compra de dívida)
refinanced_credit_operations[].original_contract_numberraiz do payloadContrato externo (portabilidade)
refinanced_credit_operations[].original_financial_institution_document_numberraiz do payloadCNPJ banco origem (portabilidade)
refinanced_credit_operations[].due_balanceraiz do payloadSaldo devedor externo
refinanced_credit_operations[].original_deadlineraiz do payloadVencimento original
modality.coderaiz"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.
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": {
    "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",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    {
      "original_contract_number": "00498765/BR",
      "original_financial_institution_document_number": "00000000000191",
      "due_balance": 12500.00,
      "original_deadline": "2027-08-15"
    }
  ],
  "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"
}

3. Payloads da compra de dívida (dupla + consolidador)​

A modalidade "compra de dívida" exige uma sequência de chamadas no /debt. Sempre desembolsando na conta interna do militar (ver Conta Interna para Desembolso). Os exemplos abaixo cobrem 1 dupla + 1 consolidador. Em produção, esse padrão se repete N vezes (uma dupla por contrato externo).

Op A — debt_purchase (ponte que carrega o saldo externo)​

Request Body — Op A (debt_purchase)
{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "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",
    "person_type": "natural",
    "individual_document_number": "45507529710",
    "gender": "male",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "single"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 420.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 48,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "operation_type": "debt_purchase",
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1167955",
    "account_digit": "1",
    "document_number": "45507529710",
    "transfer_method": "ted"
  },
  "purchaser_document_number": "32402502000135"
}

Resposta: credit_operation_key da Op A (vamos chamar de OP_A_KEY). Use no refinanced_credit_operations[].operation_key da Op B abaixo.

Op B — refinancing com port enrustida (quita Op A + carrega contrato externo)​

Request Body — Op B (refinancing port-enrustido)
{
  "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"
  },
  "operation_type": "refinancing",
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "creation",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    {
      "operation_key": "OP_A_KEY",
      "original_contract_number": "00498765/BR",
      "original_financial_institution_document_number": "00000000000191",
      "due_balance": 12500.00,
      "original_deadline": "2027-08-15"
    }
  ],
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1167955",
    "account_digit": "1",
    "document_number": "45507529710",
    "transfer_method": "ted"
  },
  "purchaser_document_number": "32402502000135"
}

refinanced_credit_operations[0] (na raiz) carrega AMBOS os links — operation_key (interno, quita Op A) E os campos do contrato externo (original_contract_number, original_financial_institution_document_number, due_balance, original_deadline). Esse é o "port enrustido": o registro carrega as duas semânticas no mesmo array.

Resposta: credit_operation_key da Op B. Repita o par Op A + Op B para cada dívida externa que o militar quer trazer.

(Opcional) Refinanciamento consolidador — refina várias Op Bs em uma só​

Request Body — refinanciamento consolidador
{
  "borrower": { "person_type": "natural", "individual_document_number": "45507529710" },
  "financial": {
    "first_due_date": "2026-08-01",
    "installment_face_value": 1200.00,
    "disbursement_date": "2026-07-02",
    "number_of_installments": 48,
    "monthly_interest_rate": 0.0175,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "operation_type": "refinancing",
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "creation",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    { "operation_key": "OP_B1_KEY" },
    { "operation_key": "OP_B2_KEY" },
    { "operation_key": "OP_B3_KEY" }
  ],
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1167955",
    "account_digit": "1",
    "document_number": "45507529710",
    "transfer_method": "ted"
  },
  "purchaser_document_number": "32402502000135"
}

O consolidador refinancia as N Op Bs num único contrato. QI desaverba todas as Op Bs originais no Zetra e averba a nova consolidada.

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​

WebhookQuando dispara
credit_transfer.received_portabilityBanco origem confirmou portabilidade (port apenas)
credit_transfer_status_changeAtualização credit-transfer (pending → accepted → confirmed)
credit_operation.collateral (reservation_status: deleted)Desaverbação da operação original confirmada

Falhas específicas​

EnumeradorQuandoAção
origin_contract_not_foundContrato externo referenciado não existe ou foi quitadoVerificar dados; pode cancelar operação
waiting_for_origin_contract_closureQI averba só após confirmar quitação do externoAguardar (retry automático)
expired_portabilityJanela de portabilidade fechou no ZetraRe-tentar com novo contrato origem
INVALID_MODALITY_CODErefin/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