Portabilidade + Refinanciamento

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

Diferença vs Margem Livre

Margem Livre (new_credit) cria nova dedução em folha. Refinanciamento (refinancing) reaproveita uma reserva existente.

Quando usar cada um

Refinanciamento puro

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

• reservation_type: refinancing
• reservation_method: issuing
• refinanced_credit_operations: [{"operation_key": "<UUID da CO QI original>"}]
• modality.code: "0202"

Portabilidade pura

Cliente tem dívida em outro banco. Quer migrar pra QI sem troco. O servidor precisa autorizar a portabilidade no Portal do Servidor — sem isso, averbação falha com consent_refused.

• reservation_type: refinancing
• refinanced_credit_operations[]: com original_contract_number + original_financial_institution_document_number + due_balance + original_deadline
• modality.code: "0202"

Compra-de-dívida (com troco)

Cliente quer migrar dívida externa e liberar troco. SIAPE não tem CTC (a câmara de portabilidade só existe pro INSS), então QI implementa via compra-de-dívida operacional:

1. QI emite operação-ponte.
2. Saldo cobre o due_balance da operação externa.
3. QI quita externamente.
4. Margem liberada no SIGEPE.
5. QI averba a operação consignada nova.
6. final_disbursement_amount na simulação é o troco.

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

Pré-requisitos

• Servidor pré-autorizou QI SCD no Portal do Servidor.
• 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": "25256363506" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 400.00,
    "disbursement_date": "2026-06-02",
    "number_of_installments": 60,
    "monthly_interest_rate": 0.0175,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "collaterals": [{
    "collateral_type": "federal_payroll",
    "percentage": 1,
    "collateral_data": {
      "reservation_type": "refinancing",
      "authority_code": "17000",
      "registration_code": "1354387",
      "refinanced_credit_operations": [
        { "operation_key": "9c8e7d6b-..." }
      ]
    }
  }],
  "modality": { "code": "0202" }
}

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

{
  "borrower": { "person_type": "natural", "individual_document_number": "25256363506" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 480.00,
    "disbursement_date": "2026-06-02",
    "number_of_installments": 72,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb"
  },
  "collaterals": [{
    "collateral_type": "federal_payroll",
    "percentage": 1,
    "collateral_data": {
      "reservation_type": "refinancing",
      "authority_code": "17000",
      "registration_code": "1354387",
      "refinanced_credit_operations": [{
        "original_contract_number": "526985/WU",
        "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
refinanced_credit_operations[].original_deadline	Vencimento original
modality.code	"0202" (obrigatório)

Response

final_disbursement_amount = troco (zero = portabilidade pura).

2. Emissão

ENDPOINT

/debt

MÉTODO

POST

Mesmo payload da simulação, acrescentando borrower completo + disbursement_bank_account + purchaser_document_number. Ver exemplo completo em Margem Livre e adaptar collateral_data conforme tabs acima.

O que acontece após o /debt (portabilidade)

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. Servidor confirma a portabilidade no Portal do Servidor.
4. Aguarda desaverbação do SIGEPE na operação original → webhook credit_operation.collateral com reservation_status: deleted.
5. Averba a nova operação → webhook credit_operation.collateral com success na nova.
6. 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
credit_transfer_status_change	Atualização credit-transfer
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 não existe ou foi quitado	Verificar; cancelar
waiting_for_origin_contract_closure	Aguardando quitação externa	Aguardar (retry automático)
expired_portability	Janela de port fechou no SIGEPE	Re-tentar
consent_refused	Servidor não autorizou no Portal	Pedir autorização
INVALID_MODALITY_CODE	Sem modality.code: "0202"	Adicionar

→ Cancelamento e Reversal