跳到主要内容

Conta Interna para Desembolso

Em compra de dívida, portabilidade e refinanciamento consignado, 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.

Por que conta interna?

Concentrar o desembolso numa conta operacional dá controle do fluxo: a QI consegue orquestrar quitação externa + averbação + repasse de troco sem depender de SLA de banco terceiro no meio do processo.

Quando usar conta interna vs externa​

Cenáriodisbursement_bank_account
Margem Livre (crédito novo direto)Conta externa do tomador
Refinanciamento puro (renegocia CO QI ativa)Conta interna em nome do tomador
Portabilidade (com ou sem troco)Conta interna em nome do tomador
Compra de dívida (debt_purchase + refinancing port-enrustido)Conta interna em nome do tomador nas duas operações da dupla
Refin/refin consolidador (opcional, fecha várias port/refins)Conta interna em nome do tomador

1. Abrir a conta interna em nome do tomador​

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
}
Pré-requisito

O tomador precisa estar onboarded previamente (ter person_key) — o parceiro envia esse person_key no owner_person_key. Caso contrário, o /account falha com ACC000xxx por validation.

Response Body
{
  "account_key": "602de111-21e1-4c1e-8c5c-d60c032309ca",
  "account_branch": "0001",
  "account_number": "1431704",
  "account_digit": "3",
  "owner_document_number": "<CPF DO TOMADOR>",
  "owner_name": "<NOME DO TOMADOR>",
  "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.

2. Usar a conta no /debt​

Use os dados retornados em disbursement_bank_account no payload do POST /debt. A mesma conta vai nas DUAS operações da dupla debt_purchase + refinancing (e no refinancing consolidador, se houver).

{
  "disbursement_bank_account": {
    "name": "<NOME DO TOMADOR>",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1431704",
    "account_digit": "3",
    "document_number": "<CPF DO TOMADOR>",
    "transfer_method": "ted"
  }
}
CampoValor (conta interna QI Tech)
bank_code"329" (QI Tech S.A. — SCD)
account_branch"0001"
account_number / account_digitretornados no POST /account
document_numberCPF do tomador (mesmo do owner_document_number)
transfer_method"ted" (recomendado para payment_type_id: 10)

Exemplo completo: ver Portabilidade + Refinanciamento — Compra de dívida.

3. Ações pós-desembolso​

A QI dispara as ações abaixo automaticamente conforme os webhooks confirmam cada etapa.

3.1 Conferir saldo​

ENDPOINT
/account/ACCOUNT_KEY/balance
MÉTODO
GET

3.2 Quitação do contrato externo (port)​

Disparada pela QI ao receber credit_operation.collateral (reservation_status: deleted) na operação antiga: saldo da conta interna é enviado ao banco origem via PIX ou TED para liquidar o contrato externo.

3.3 Repasse de troco pro tomador (se houver)​

Se final_disbursement_amount > 0 na simulação, o saldo residual é transferido da conta interna para a conta externa do tomador (informada no onboarding ou no payload da operação).

3.4 Conciliação​

ENDPOINT
/account/ACCOUNT_KEY/statement
MÉTODO
GET

Query params from_date e to_date no formato YYYY-MM-DD.

3.5 Webhooks relevantes​

WebhookQuando dispara
account.balance_changeCrédito recebido na conta interna (desembolso da CO)
pix_transfer.status_changeQuitação externa OU repasse de troco confirmados
ted.status_changeQuitação externa OU repasse via TED confirmados

Referências​