跳到主要内容

Compra de dívida veicular

Fluxo de compra de dívida de financiamento de veículo via assinatura em lote. A QI Tech emite uma CCB de quitação (debt_purchase), que paga a financeira de origem, e uma CCB de portabilidade (portability), que é o contrato novo do tomador com o veículo como garantia. Para mudar as condições do contrato ou pagar troco ao tomador, o lote recebe também um refinancing, que refinancia a portability. Tudo é assinado de uma única vez no QI Sign, e o gravame do veículo é portado para a QI Tech no SNG (B3).

Os corpos de requisição desta página funcionam como estão: copie, troque os valores indicados em cada passo e envie.

Contas por operação
  • debt_purchase e portability → conta interna QI em nome do tomador, aberta no Passo 2. O desembolso da debt_purchase cai nessa conta e quita a financeira de origem via after_disbursement_actions (boleto).
  • refinancing → conta externa do tomador. É para onde vai o troco.

Cenários​

CenárioComposição do loteQuando usar
Sem refinanciamento1× debt_purchase + 1× portabilityO contrato vem para a QI Tech nas condições do contrato original, com taxa igual ou menor
Com refinanciamento1× debt_purchase + 1× portability + 1× refinancingO contrato muda de condições — taxa, parcela, prazo — com ou sem troco

A debt_purchase e a portability são obrigatórias, exatamente uma de cada. O refinancing é opcional, no máximo um por lote, e é a única operação que aceita troco e seguro.

Sequência de requisições​

1. POST /upload
2. POST /account
3. POST /document/document_batch
4. POST /debt debt_purchase
5. POST /debt portability
6. POST /debt (opcional) refinancing
7. PUT /document/document_batch/{document_batch_key}/send_to_signature

# Aguardar portability status = pending_reservation_confirmation
8. GET /debt/{portability_key}/vehicle_collateral/reservation

# Permitir desembolso da debt_purchase
9. POST /debt/{debt_purchase_key}/allow_disbursement

10. GET /debt/{portability_key}/vehicle_collateral/reservation
11. POST /debt/{key}/allow_disbursement
12. GET /debt?key={key}
Ordem obrigatória de inserção no lote

A debt_purchase entra antes da portability, e a portability antes do refinancing. Cada operação só pode referenciar uma que já esteja no lote: fora dessa ordem, a criação retorna DOC000110 (portability) ou DOC000112 (refinancing).


1. Upload do documento do tomador​

Envie o documento de identificação do tomador (por exemplo, a frente do RG) por POST /upload, como multipart/form-data. Autenticação, headers e exemplos de código estão em Upload de Documentos.

Guarde o document_key da resposta: ele substitui <document_key>.


2. Abrir a conta interna em nome do tomador​

Abra a conta por POST /account. Use uma conta por tomador: se ela já existir, consulte GET /accounts?owner_document_number=12345678909 e reaproveite os dados. Detalhes em Conta Interna para Desembolso.

Corpo da requisição
{
"account_owner": {
"person_type": "natural",
"name": "JOÃO DA SILVA",
"email": "joao@email.com",
"individual_document_number": "12345678909",
"mother_name": "MARIA DA SILVA",
"birth_date": "1985-03-12",
"is_pep": false,
"document_identification": "<document_key>",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"address": {
"street": "Rua Exemplo",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Centro",
"number": "100",
"postal_code": "01310100"
}
}
}
SubstituaPor
<document_key>document_key do Passo 1
Resposta
{
"account_key": "1167955-...",
"account_branch": "0001",
"account_number": "1167955",
"account_digit": "1",
"owner_document_number": "12345678909",
"owner_name": "JOÃO DA SILVA",
"bank_code": "329",
"account_status": "active"
}

Guarde account_number e account_digit: eles substituem <account_number> e <account_digit>.


3. Abrir o lote​

Abra o lote por POST /document/document_batch (Assinatura em Lote).

Corpo da requisição
{
"type": "vehicle_debt_purchase_external_batch",
"certifier_type": "qi_sign",
"batch_name": "Lote veículo compra de dívida - 3f1c2a9e-7b4d-4e21-9a6f-1d2c3b4a5e6f",
"request_control_key": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d"
}
SubstituaPor
batch_nameNome novo, até 100 caracteres, a cada lote
request_control_keyUUIDv4 novo a cada lote
Resposta
{
"document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}

Guarde o document_batch_key: ele substitui <document_batch_key>.


4. Emitir a debt_purchase​

CCB de quitação do financiamento de origem, emitida por POST /debt (Simulação e Emissão).

Particularidades da debt_purchase
  • Não leva o veículo: collaterals é vazio.
  • financial.disbursed_amount é o valor de quitação informado pela financeira de origem.
  • Tomador e condições financeiras são os do contrato original.
  • Nasce bloqueada para desembolso até que a portabilidade esteja intencionada, qualquer que seja a configuração do seu requester.
Corpo da requisição
{
"borrower": {
"name": "JOÃO DA SILVA",
"email": "joao@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "100",
"street": "Rua Exemplo",
"complement": "",
"postal_code": "01310100",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1985-03-12",
"mother_name": "MARIA DA SILVA",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"individual_document_number": "12345678909",
"document_identification": "<document_key>"
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2026-11-16",
"first_due_date": "2027-01-15",
"limit_days_to_disburse": 3,
"number_of_installments": 36,
"monthly_interest_rate": 0.0199,
"disbursed_amount": 25000.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
},
"collaterals": [],
"disbursement_bank_account": {
"bank_code": "329",
"branch_number": "0001",
"account_number": "<account_number>",
"account_digit": "<account_digit>",
"document_number": "12345678909",
"name": "JOÃO DA SILVA"
},
"purchaser_document_number": "<purchaser_document_number>",
"document_batch_key": "<document_batch_key>",
"after_disbursement_actions": [
{
"action_type": "bankslip_payment",
"action_data": {
"qr_code": null,
"destination": null,
"digitable_line": "03399199530490000005237385601010297590005474921",
"pix_transfer_type": null,
"transaction_amount": 0
}
}
]
}
SubstituaPor
<document_key>document_key do Passo 1
<account_number> e <account_digit>Conta interna do Passo 2
<document_batch_key>document_batch_key do Passo 3
<purchaser_document_number>CNPJ do comprador da sua integração
2026-11-16Data de hoje
2027-01-15Próximo vencimento do contrato original

Em produção, troque também borrower, number_of_installments e monthly_interest_rate pelos dados do contrato original, e disbursed_amount e digitable_line pelo valor e pelo boleto de quitação da financeira de origem.

Resposta
{
"proposal_id": "<id interno>",
"status": 200,
"key": "<key da debt_purchase>",
"data": {
"credit_operation_key": "<mesmo valor de key>",
"status": "waiting_signature"
}
}

Guarde a key: ela substitui <debt_purchase_key> no Passo 5 e na autorização do Passo 9.


5. Emitir a portability​

CCB de portabilidade, emitida por POST /debt (Simulação e Emissão). É o contrato novo do tomador que vai portar.

Particularidades da portability
  • Leva o veículo com reservation_type: "portability" e os dados do contrato na financeira de origem em portability_data. É com eles que a QI Tech pede a intenção de gravame no SNG.
  • Não tem troco nem seguro: final_disbursement_amount é sempre 0.
A portability repete o contrato original

Todos os dados devem ser iguais aos do contrato na financeira de origem: tomador (borrower), vendedor (seller), veículo (vehicle), licenciamento (license_state, plate_state, credit_release_postal_code) e condições financeiras (number_of_installments, first_due_date). Só mudam os dados da QI Tech como nova credora e a taxa (monthly_interest_rate), que pode ser menor que a do contrato original.

Corpo da requisição
{
"borrower": {
"name": "JOÃO DA SILVA",
"email": "joao@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "100",
"street": "Rua Exemplo",
"complement": "",
"postal_code": "01310100",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1985-03-12",
"mother_name": "MARIA DA SILVA",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"individual_document_number": "12345678909",
"document_identification": "<document_key>"
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2026-11-16",
"first_due_date": "2027-01-15",
"limit_days_to_disburse": 3,
"number_of_installments": 36,
"monthly_interest_rate": 0.015,
"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
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "vehicle",
"collateral_data": {
"vehicle": {
"vehicle_type": "automobile",
"plate": "ABC1D23",
"plate_state": "SP",
"license_state": "SP",
"renavam": "12345678900",
"chassis": "9BWZZZ37780001234",
"chassis_type": "normal",
"model": "GOL 1.0",
"model_year": 2022,
"manufacturing_year": 2021
},
"seller": {
"document_number": "12345678000195",
"name": "CONCESSIONÁRIA EXEMPLO LTDA"
},
"reservation_type": "portability",
"portability_data": {
"origin_contract": {
"contract_number": "123456789",
"financial_institution_document_number": "11222333000181"
}
},
"credit_release_postal_code": "01310100"
}
}
],
"modality": {
"code": "0203"
},
"disbursement_bank_account": {
"bank_code": "329",
"branch_number": "0001",
"account_number": "<account_number>",
"account_digit": "<account_digit>",
"document_number": "12345678909",
"name": "JOÃO DA SILVA"
},
"purchaser_document_number": "<purchaser_document_number>",
"document_batch_key": "<document_batch_key>",
"refinanced_credit_operations": [
{
"operation_key": "<debt_purchase_key>"
}
]
}
SubstituaPor
<debt_purchase_key>key da debt_purchase do Passo 4
<document_key>, <account_number>, <account_digit>, <document_batch_key>, <purchaser_document_number>Os mesmos valores do Passo 4
2026-11-16 e 2027-01-15As mesmas datas do Passo 4
chassisOutro chassi a cada teste

Em produção, troque borrower, seller, vehicle, credit_release_postal_code, number_of_installments e first_due_date pelos dados do contrato original, monthly_interest_rate pela taxa da portabilidade, e portability_data.origin_contract pelo número do contrato e pelo CNPJ da financeira de origem.

Resposta
{
"proposal_id": "<id interno>",
"status": 200,
"key": "<key da portability>",
"data": {
"credit_operation_key": "<mesmo valor de key>",
"status": "waiting_signature"
}
}

Guarde a key: ela substitui <portability_key> no Passo 6 e identifica a reserva do veículo nos Passos 8 e 10.


6. (Opcional) Emitir o refinancing​

Refinanciamento ainda não disponível

O refinancing na compra de dívida veicular está em desenvolvimento e ainda não pode ser usado. Por enquanto, o lote aceita apenas a portabilidade: uma debt_purchase e uma portability. Pule para o Passo 7.

CCB de refinanciamento, emitida por POST /debt (Simulação e Emissão). Use só no cenário com refinanciamento: o refinancing refinancia a portability, liquida o saldo dela e paga o troco, se houver, na conta externa do tomador. Sem refinanciamento, pule para o Passo 7.

Particularidades do refinancing
  • Seguro é opcional e exige seguro habilitado no seu requester: inclua financial.rebates com fee_type: "insurance_premium_qi". No máximo um seguro por lote.
Corpo da requisição
{
"borrower": {
"name": "JOÃO DA SILVA",
"email": "joao@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "100",
"street": "Rua Exemplo",
"complement": "",
"postal_code": "01310100",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1985-03-12",
"mother_name": "MARIA DA SILVA",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"individual_document_number": "12345678909",
"document_identification": "<document_key>"
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2026-11-16",
"first_due_date": "2027-01-15",
"limit_days_to_disburse": 3,
"number_of_installments": 48,
"monthly_interest_rate": 0.016,
"final_disbursement_amount": 5000.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
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "vehicle",
"collateral_data": {
"vehicle": {
"vehicle_type": "automobile",
"plate": "ABC1D23",
"plate_state": "SP",
"license_state": "SP",
"renavam": "12345678900",
"chassis": "9BWZZZ37780001234",
"chassis_type": "normal",
"model": "GOL 1.0",
"model_year": 2022,
"manufacturing_year": 2021
},
"seller": {
"document_number": "12345678000195",
"name": "CONCESSIONÁRIA EXEMPLO LTDA"
},
"reservation_type": "refinancing",
"credit_release_postal_code": "01310100"
}
}
],
"modality": {
"code": "0203"
},
"disbursement_bank_account": {
"bank_code": "001",
"branch_number": "1234",
"account_number": "567890",
"account_digit": "1",
"document_number": "12345678909",
"name": "JOÃO DA SILVA"
},
"purchaser_document_number": "<purchaser_document_number>",
"document_batch_key": "<document_batch_key>",
"refinanced_credit_operations": [
{
"operation_key": "<portability_key>"
}
]
}
SubstituaPor
<portability_key>key da portability do Passo 5
<document_key>, <document_batch_key>, <purchaser_document_number>Os mesmos valores do Passo 4
2026-11-16 e 2027-01-15As mesmas datas do Passo 4
vehicle e sellerOs mesmos do Passo 5

Em produção, troque também monthly_interest_rate, number_of_installments e final_disbursement_amount pelas condições negociadas, disbursement_bank_account pela conta externa real do tomador, e borrower, seller, vehicle e credit_release_postal_code pelos dados do contrato original.

Resposta
{
"proposal_id": "<id interno>",
"status": 200,
"key": "<key do refinancing>",
"data": {
"credit_operation_key": "<mesmo valor de key>",
"status": "waiting_signature"
}
}

7. Enviar para assinatura​

Feche o lote com PUT /document/document_batch/{document_batch_key}/send_to_signature (Assinatura em Lote), trocando {document_batch_key} na URL. O envelope é criado no QI Sign; antes desse envio, nada chega ao tomador. Depois do envio, o lote não aceita novas operações (DOC000146).

Corpo da requisição
{}

A resposta é HTTP 200.

Conferir antes de enviar

Use GET /document/document_batch/{document_batch_key} para confirmar a composição do lote antes do envio. Ver Assinatura em Lote.

CódigoHTTPQuando
DOC000144422Lote sem a debt_purchase ou sem a portability
DOC000145422portability ou refinancing que não referencia exatamente uma operação
DOC000110422portability referenciando operação que não é a debt_purchase do lote
DOC000112422refinancing referenciando operação que não é a portability do lote
DOC000109422Mais de um refinancing no lote
DOC000116422Mais de um termo de seguro no lote

Depois que o tomador assina, as operações do lote vão para issued e você recebe o webhook de debt com signature_finished. A reserva do veículo é criada para a portability e a QI Tech pede ao SNG a intenção de gravame por portabilidade, sem requisição sua.


8. Acompanhar a intenção de gravame​

Consulte a reserva da portability por GET /debt/{portability_key}/vehicle_collateral/reservation (Consultas) até ela chegar a pending_reservation_confirmation. Quando o SNG devolve o protocolo da intenção, você também recebe o webhook laas.vehicle_collateral.reservation.status_change.

Resposta e webhook
{
"status": "pending_reservation_confirmation",
"last_updated_at": "2026-11-16 10:05:00",
"chassi_number": "9BWZZZ37780001234",
"license_state": "SP",
"collateral_number": "0"
}

9. Autorizar a quitação​

Com a intenção de gravame registrada, autorize o desembolso da debt_purchase por POST /debt/{debt_purchase_key}/allow_disbursement (Autorizar desembolso), trocando {debt_purchase_key} na URL. A QI Tech confere a reserva da portability e, se ela estiver em pending_reservation_confirmation, desembolsa a debt_purchase na conta interna e paga o boleto de quitação da financeira de origem.

Corpo da requisição
{
"allow_disbursement": true
}

A resposta traz a debt_purchase com is_allowed_to_disburse: true. Ao fim, você recebe o webhook de debt com a debt_purchase desembolsada.

Quitação só com a intenção registrada

A autorização é recusada, e nada é desembolsado, quando:

  • a reserva da portability ainda não está em pending_reservation_confirmation — COP000634. Espere o Passo 8 e tente de novo;
  • nenhuma portability ativa refinancia a debt_purchase (por exemplo, a portability foi cancelada) — COP000635.

Próximo passo​

Acompanhe a reserva do veículo e o registro do contrato em Consultas e pelos eventos de Webhooks.