Portabilidade + Refinanciamento

Fluxo de compra de dívida consignada SIAPE 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 de uma única vez na 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 federal — é 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 5).

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 /upload   (documentos da operação)

 POST /account  (conta interna QI p/ debt_purchase)

 POST /document/document_batch

 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.

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.

2. Abrir a conta interna em nome do tomador

Em compra de dívida, portabilidade e refinanciamento do consignado federal (Siape), 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 o owner_document_number apontando para o CPF do tomador. Reutilize a conta existente — uma por tomador (não abrir nova a cada operação).

Request Body

{
  "owner_document_number": "<CPF DO TOMADOR>",
  "owner_person_key": "<PERSON_KEY DO TOMADOR>",
  "requester_key": "<REQUESTER_KEY DO PARCEIRO>",
  "webhook_enabled": true
}

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",
  "webhook_enabled": true
}

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": "federal_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote SIAPE portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>"
}

Campos chave

Campo	Tipo	Descrição
`type`	string	Fixo: `federal_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

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).
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": "MARIA DOS SANTOS",
    "email": "maria@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "055" },
    "is_pep": false,
    "address": {
      "city": "Brasília",
      "state": "DF",
      "number": "100",
      "street": "Esplanada dos Ministérios",
      "complement": "",
      "postal_code": "70000000",
      "neighborhood": "Centro"
    },
    "role_type": "issuer",
    "birth_date": "1978-09-22",
    "mother_name": "JOSEFINA DOS SANTOS",
    "nationality": "Brasileiro",
    "person_type": "natural",
    "marital_status": "married",
    "individual_document_number": "25256363506",
    "gender": "female",
    "document_identification_type": "rg",
    "document_identification_number": "1234567",
    "document_identification_date": "2015-01-01"
  },
  "financial": {
    "first_due_date": "2026-06-10",
    "installment_face_value": 100,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "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": "7",
    "branch_number": "0001",
    "account_number": "4944068",
    "document_number": "25256363506",
    "name": "MARIA DOS SANTOS"
  },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 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 2
`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
`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_data.portability_data é obrigatório — contém os dados do contrato de origem na instituição vendedora.
refinanced_credit_operations carrega a key do debt_purchase correspondente.

Portabilidade sem seguro e sem troco

Em batch federal, 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-06-10",
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "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": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "portability",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": "",
        "portability_data": {
          "start_date": "2024-06-24",
          "control_number": "57309647149",
          "origin_contract": {
            "contract_number": "866415127",
            "financial_institution_document_number": "90400888000142"
          }
        }
      }
    }
  ],
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "mesmo disbursement do Passo 4" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 2>",
  "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 2
`refinanced_credit_operations[0].operation_key`	✅ Sim	`key` do `debt_purchase` referenciado (Passo 4)
`collaterals[0].collateral_data.registration_code`	✅ Sim	Matrícula SIAPE do servidor
`collaterals[0].collateral_data.authority_code` / `authority.description` / `authority.authority_document_number`	✅ Sim	Órgão pagador (UPAG)
`portability_data.start_date`	✅ Sim	Data de início do contrato de origem
`portability_data.control_number`	✅ Sim	Número de controle no SIAPE
`portability_data.origin_contract.contract_number`	✅ Sim	Nº do contrato na instituição vendedora
`portability_data.origin_contract.financial_institution_document_number`	✅ Sim	CNPJ da instituição vendedora
`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 5) no cenário β.

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 federal não aceita seguro

6. Emitir `refinancing` consolidador

CCB mãe que consolida as portabilidades num único instrumento. Sempre obrigatória no batch federal — 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

reservation_type: "refinancing" no collateral_data.
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.
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-06-10",
    "installment_face_value": 1000,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "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": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "refinancing",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": ""
      }
    }
  ],
  "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 2>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ]
}

{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-06-10",
    "installment_face_value": 1500,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "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": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "refinancing",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": ""
      }
    }
  ],
  "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 2>",
  "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 2
`refinanced_credit_operations`	✅ Sim	Todas as `key` das portabilidades emitidas no Passo 5
`collaterals[0].collateral_data.authority.*` / `authority_code` / `registration_code`	✅ Sim	Conforme órgão e servidor
`reservation_method`	✅ Sim	Sempre `"issuing"` para o consolidador
`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`

7. Enviar para assinatura

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

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 federal
`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`

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 federal_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
SIAPE	Sistema Integrado de Administração de Recursos Humanos do Governo Federal — folha de pagamento dos servidores da União
UPAG	Unidade Pagadora — órgão da União que paga o salário do servidor (identificado por `authority_code` + `authority_document_number`)
matrícula SIAPE	`registration_code` — identificador do servidor na folha
portability_data	Dados do contrato de origem na instituição vendedora (`start_date`, `control_number`, `contract_number`, `financial_institution_document_number`)
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​

1. Upload dos documentos​

2. Abrir a conta interna em nome do tomador​

3. Abrir o lote​

Campos chave​

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

1. Upload dos documentos

2. Abrir a conta interna em nome do tomador

3. Abrir o lote

Campos chave

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