Simulação e Emissão
API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
Simulação da dívida
Antes de emitir a operação, simule as condições financeiras enviando os dados básicos com o tipo de garantia vehicle. As taxas de registro variam por região do Detran, por isso os dados da garantia são necessários para uma simulação financeira precisa.
Request
POST
/debt_simulationRequest Body
{
"borrower": {
"person_type": "natural"
},
"financial": {
"first_due_date": "2025-06-15",
"installment_face_value": 500,
"disbursement_date": "2025-05-10",
"limit_days_to_disburse": 3,
"number_of_installments": 12,
"monthly_interest_rate": 0.018,
"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
},
"collaterals": [
{
"collateral_type": "vehicle",
"collateral_data": {
"vehicle_type": "car",
"licensing_state": "SP"
}
}
]
}
informação
A simulação aceita tanto installment_face_value (fixando o valor de parcela, variando o desembolso) quanto disbursed_amount (fixando o valor desembolsado, variando a parcela). O campo collateral_type deve ser "vehicle". Para simulação, os campos obrigatórios em collateral_data são vehicle_type e licensing_state — as taxas variam por região do Detran.
Response
STATUS
200 (OK)Response Body
{
"type": "debt",
"key": "<Debt Key>",
"status": "finished",
"event_datetime": "2025-05-10 16:50:00",
"data": {
"interest_type": "pre_price_days",
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"principal_grace_period": 0,
"operation_type": "structured_operation",
"prefixed_interest_rate": {
"interest_base": "calendar_days_365",
"annual_rate": 0.23872053,
"monthly_rate": 0.018,
"daily_rate": 0.00058669
},
"issue_date": "2025-05-10",
"number_of_installments": 12,
"disbursement_options": [
{
"iof_amount": 25.50,
"total_pre_fixed_amount": 580.45,
"cet": 0.0230,
"annual_cet": 0.3120,
"contract_fees": [
{
"fee_type": "registration_fee",
"amount_type": "absolute",
"amount": 1.0,
"fee_amount": 350.00
}
],
"external_contract_fees": [],
"contract_fee_amount": 350.00,
"external_contract_fee_amount": 0.0,
"disbursement_date": "2025-05-10",
"first_due_date": "2025-06-15",
"installments": [
{
"calendar_days": 36,
"business_due_date": "2025-06-15",
"due_date": "2025-06-15",
"due_principal": 5419.55,
"has_interest": true,
"pre_fixed_amount": 114.65,
"tax_amount": 1.25,
"total_amount": 500,
"principal_amortization_amount": 385.35,
"installment_number": 1
}
],
"issue_amount": 5419.55,
"disbursed_issue_amount": 5044.05,
"assignment_amount": 5419.55,
"final_disbursement_amount": 5044.05,
"prefixed_interest_rate": {
"interest_base": "calendar_days_365",
"annual_rate": 0.23872053,
"monthly_rate": 0.018,
"daily_rate": 0.00058669
}
}
]
}
}
Objeto Installments
| Campo | Descrição |
|---|---|
| calendar_days | Dias corridos |
| business_due_date | Data de vencimento em dia útil |
| due_date | Data de vencimento |
| due_principal | Principal do vencimento |
| has_interest | Indica se o vencimento possui juros |
| pre_fixed_amount | Valor pré-fixado da parcela |
| tax_amount | Valor de imposto da parcela |
| total_amount | Valor total da parcela |
| principal_amortization_amount | Valor da amortização do principal |
| installment_number | Número da parcela |
Objeto Prefixed Interest Rate
| Campo | Descrição |
|---|---|
| monthly_rate | Taxa mensal |
| daily_rate | Taxa diária |
| annual_rate | Taxa anual |
| interest_base | Base de cálculo da taxa de juros |
Objeto Contract Fees
| Campo | Tipo | Descrição |
|---|---|---|
| fee_type | String | Tipo da taxa (ex: registration_fee) |
| amount_type | String | Tipo de valor (absolute ou percentage) |
| amount | Float | Multiplicador ou percentual aplicado |
| fee_amount | Float | Valor monetário final da taxa |
Taxas de Registro
As taxas gerais de registro (DETRAN, SNG/B3) são refletidas diretamente no campo contract_fee_amount dentro de disbursement_options. O valor total das taxas é descontado do valor de emissão (issue_amount), não do valor líquido de desembolso.
Emissão da operação
Após simular e validar as condições, emita a operação de crédito com garantia veicular. O request body inclui os dados do tomador, financeiros, garantia veicular e conta para desembolso.
Request
POST
/debtRequest Body
{
"borrower": {
"name": "Nome do Devedor",
"email": "devedor@email.com",
"phone": {
"number": "999999999",
"area_code": "11",
"country_code": "055"
},
"gender": "male",
"political_exposition": "not_exposed",
"address": {
"city": "São Paulo",
"state": "SP",
"number": "100",
"street": "Rua Exemplo",
"complement": "Apto 10",
"postal_code": "01001000",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1990-01-15",
"mother_name": "NOME DA MAE",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"attached_documents_list": [],
"individual_document_number": "12345678901",
"document_identification_date": "2015-10-02",
"document_identification_type": "rg",
"document_identification_number": "123456789"
},
"financial": {
"interest_type": "pre_price_days",
"first_due_date": "2025-06-15",
"disbursement_date": "2025-05-10",
"fine_configuration": {
"monthly_rate": 0.01,
"interest_base": "calendar_days",
"contract_fine_rate": 0.02
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"monthly_interest_rate": 0.018,
"installment_face_value": 500,
"limit_days_to_disburse": 3,
"number_of_installments": 12,
"principal_grace_period": 0
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "vehicle",
"collateral_data": {
"vehicle_type": "car",
"plate": "ABC1D23",
"licensing_state": "SP",
"licensing_city": "São Paulo",
"renavam": "12345678901",
"chassi_type": "Remarcado",
"chassi_number": "9BWZZZ37780001234",
"kilometers": 45000,
"car_color": "Prata",
"car_value": 85000.00,
"subcorban_document_number": "12345678000195",
"model": {
"brand": "Toyota",
"name": "Corolla XEI 2.0",
"year": "2022",
"manufacturing_year": "2021"
},
"seller": {
"name": "João da Silva Automóveis",
"document_number": "98765432000100"
}
}
}
],
"purchaser_document_number": "12345678000199",
"disbursement_bank_accounts": [
{
"name": "NOME DO DEVEDOR",
"bank_code": "001",
"account_digit": "0",
"branch_number": "1234",
"account_number": "000012345",
"document_number": "12345678901",
"transfer_method": "pix",
"percentage_receivable": 100
}
]
}
Importante
Não é necessário chamar endpoints separados para registrar gravame ou contrato. Basta enviar os dados do veículo no objeto collaterals na criação da dívida e a QI Tech cuida de todo o processo internamente (inclusão de gravame no SNG/B3, registro do contrato no DETRAN/Registradora, envio de imagem).
Simulação
Para o POST /debt_simulation, inclua collateral_type: "vehicle" no array collaterals com collateral_data contendo no mínimo vehicle_type e licensing_state. As taxas de registro variam por região do Detran.
reservation_method
Após a criação, a API adiciona automaticamente reservation_method ao collateral_data (valor: "creation" ou "issuing" conforme configuração do requester). Este campo não deve ser enviado na requisição.
Campos do collateral_data
| Campo | Tipo | Descrição | Obrig. |
|---|---|---|---|
| vehicle_type | String | Tipo de veículo (car, motorcycle, truck) | SIM |
| plate | String | Placa do veículo (7 caracteres) | SIM |
| licensing_state | String | UF de licenciamento do veículo (2 chars, sigla caixa alta) | SIM |
| licensing_city | String | Cidade de licenciamento do veículo | SIM |
| renavam | String | Número do RENAVAM (11 dígitos) | SIM |
| chassi_type | String | Tipo de chassi (Remarcado ou Normal) | SIM |
| chassi_number | String | Número do chassi do veículo (4 a 21 caracteres, alfanumérico) | SIM |
| kilometers | Integer | Quilometragem atual do veículo | SIM |
| car_color | String | Cor do veículo | SIM |
| car_value | Float | Valor do veículo (2 casas decimais) | SIM |
| subcorban_document_number | String | CNPJ do correspondente bancário (14 dígitos) | NÃO |
Objeto model
| Campo | Tipo | Descrição | Obrig. |
|---|---|---|---|
| brand | String | Marca do veículo | SIM |
| name | String | Nome do modelo do veículo | SIM |
| year | String | Ano do modelo | SIM |
| manufacturing_year | String | Ano de fabricação | SIM |
Objeto seller
| Campo | Tipo | Descrição | Obrig. |
|---|---|---|---|
| name | String | Nome do vendedor | SIM |
| document_number | String | CPF (11 dígitos) ou CNPJ (14 dígitos) do vendedor | SIM |
Response
STATUS
201 (Created)Response Body
Response Body
{
"webhook_type": "debt",
"key": "<Debt Key>",
"status": "waiting_signature",
"event_datetime": "2025-05-10 14:30:00",
"data": {
"borrower": {
"name": "Nome do Devedor",
"document_number": "12345678901",
"related_party_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"contract": {
"number": "OP-000000000000001",
"urls": [
"https://storage.googleapis.com/doc-api/documents/<uuid>/NOME_DO_DEVEDOR-CCB-OP000000000000001.pdf"
],
"signature_information": [
{
"signer_name": "Nome do Devedor",
"signer_document_number": "12345678901",
"signer_role": "issuer",
"signer_email": null,
"signer_external_key": null,
"signature_url": null
}
]
},
"collaterals": [
{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"vehicle_type": "car",
"plate": "ABC1D23",
"licensing_state": "SP",
"licensing_city": "São Paulo",
"renavam": "12345678901",
"chassi_type": "Remarcado",
"chassi_number": "9BWZZZ37780001234",
"kilometers": 45000,
"car_color": "Prata",
"car_value": 85000.00,
"subcorban_document_number": "12345678000195",
"model": {
"brand": "Toyota",
"name": "Corolla XEI 2.0",
"year": "2022",
"manufacturing_year": "2021"
},
"seller": {
"name": "João da Silva Automóveis",
"document_number": "98765432000100"
}
},
"collateral_key": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
"collateral_type": "vehicle",
"created_at": "2025-05-10T14:30:00.000000",
"external_key": null,
"percentage": 1,
"updated_at": "2025-05-10T14:30:00.000000"
}
],
"disbursement_options": [
{
"disbursement_date": "2025-05-10",
"contract_fees": [
{
"fee_type": "registration_fee",
"amount_type": "absolute",
"amount": 1.0,
"fee_amount": 350.00
}
],
"external_contract_fees": [],
"contract_fee_amount": 350.00,
"external_contract_fee_amount": 0.0,
"assignment_amount": 5419.55,
"issue_amount": 5419.55,
"cet": "2,3000%",
"annual_cet": "31,2000%",
"total_iof": 25.50,
"total_pre_fixed_amount": 580.45,
"installments": [
{
"business_due_date": "2025-06-15",
"calendar_days": 36,
"due_date": "2025-06-15",
"due_principal": 5419.55,
"has_interest": true,
"installment_number": 1,
"pre_fixed_amount": 114.65,
"principal_amortization_amount": 385.35,
"tax_amount": 1.25,
"total_amount": 500,
"installment_status": null,
"installment_type": null
}
],
"first_due_date": "2025-06-15",
"prefixed_interest_rate": {
"monthly_rate": 0.018,
"daily_rate": 0.00058669,
"annual_rate": 0.23872053,
"interest_base": "calendar_days_365"
}
}
]
}
}
Webhook de Cancelamento
Caso a operação não seja assinada ou averbada até a última opção de data de desembolso, o parceiro receberá um webhook informando a respeito do cancelamento da operação:
WEBHOOK TYPE
debtWebhook Body
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2025-05-20 10:00:00",
"data": {
"cancel_reason": "<CANCEL_REASON>",
"cancel_reason_enumerator": "<CANCEL_REASON_ENUMERATOR>"
}
}
Enumeradores
collateral_type
| Valor | Descrição |
|---|---|
| vehicle | Garantia veicular (gravame) |
vehicle_type
| Valor | Descrição |
|---|---|
| car | Automóvel |
| motorcycle | Motocicleta |
| truck | Caminhão |
chassi_type
| Valor | Descrição |
|---|---|
| Remarcado | Chassi remarcado |
| Normal | Chassi normal (padrão) |