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.
debt_purchaseeportability→ conta interna QI em nome do tomador, aberta no Passo 2. O desembolso dadebt_purchasecai nessa conta e quita a financeira de origem viaafter_disbursement_actions(boleto).refinancing→ conta externa do tomador. É para onde vai o troco.
Cenários
| Cenário | Composição do lote | Quando usar |
|---|---|---|
| Sem refinanciamento | 1× debt_purchase + 1× portability | O contrato vem para a QI Tech nas condições do contrato original, com taxa igual ou menor |
| Com refinanciamento | 1× debt_purchase + 1× portability + 1× refinancing | O 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}
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"
}
}
}
| Substitua | Por |
|---|---|
<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"
}
| Substitua | Por |
|---|---|
batch_name | Nome novo, até 100 caracteres, a cada lote |
request_control_key | UUIDv4 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).
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
}
}
]
}
| Substitua | Por |
|---|---|
<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-16 | Data de hoje |
2027-01-15 | Pró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.
portability- Leva o veículo com
reservation_type: "portability"e os dados do contrato na financeira de origem emportability_data. É com eles que a QI Tech pede a intenção de gravame no SNG. - Não tem troco nem seguro:
final_disbursement_amounté sempre0.
portability repete o contrato originalTodos 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>"
}
]
}
| Substitua | Por |
|---|---|
<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-15 | As mesmas datas do Passo 4 |
chassis | Outro 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
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.
refinancing- Seguro é opcional e exige seguro habilitado no seu requester: inclua
financial.rebatescomfee_type: "insurance_premium_qi". No máximo um seguro por lote.
Corpo da requisição
- Com troco
- Sem troco
{
"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>"
}
]
}
{
"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": 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>"
}
]
}
| Substitua | Por |
|---|---|
<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-15 | As mesmas datas do Passo 4 |
vehicle e seller | Os 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.
Use GET /document/document_batch/{document_batch_key} para confirmar a composição do lote antes do envio. Ver Assinatura em Lote.
| Código | HTTP | Quando |
|---|---|---|
DOC000144 | 422 | Lote sem a debt_purchase ou sem a portability |
DOC000145 | 422 | portability ou refinancing que não referencia exatamente uma operação |
DOC000110 | 422 | portability referenciando operação que não é a debt_purchase do lote |
DOC000112 | 422 | refinancing referenciando operação que não é a portability do lote |
DOC000109 | 422 | Mais de um refinancing no lote |
DOC000116 | 422 | Mais 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
- GET da reserva
- Webhook
{
"status": "pending_reservation_confirmation",
"last_updated_at": "2026-11-16 10:05:00",
"chassi_number": "9BWZZZ37780001234",
"license_state": "SP",
"collateral_number": "0"
}
{
"key": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"reservation_key": "a1b2c3d4-e5f6-4890-abcd-ef0123456789",
"credit_operation_key": "<key da portability>",
"status": "pending_reservation_confirmation",
"webhook_type": "laas.vehicle_collateral.reservation.status_change",
"event_datetime": "2026-11-16T10:05:00Z",
"data": {
"contract_number": "<número do contrato>"
}
}
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.
A autorização é recusada, e nada é desembolsado, quando:
- a reserva da
portabilityainda não está empending_reservation_confirmation—COP000634. Espere o Passo 8 e tente de novo; - nenhuma
portabilityativa refinancia adebt_purchase(por exemplo, aportabilityfoi cancelada) —COP000635.
Próximo passo
Acompanhe a reserva do veículo e o registro do contrato em Consultas e pelos eventos de Webhooks.