Skip to main content

Simulation and Issuance

API under development

The API is still in development phase, therefore, this manual is subject to changes.

Debt Simulation

Before issuing the operation, simulate the financial conditions by sending the basic data with collateral type vehicle. Registration fees vary per Detran region, so the collateral data is required for an accurate financial simulation.

Request

ENDPOINT
/debt_simulation
METHOD
POST
Test in Playground
Request Body
{
"borrower": {
"person_type": "natural"
},
"financial": {
"first_due_date": "2025-06-15",
"installment_face_value": 500,
"disbursed_amount": 10000.00,
"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",
"license_state": "SP"
}
}
]
}
info

The simulation accepts both installment_face_value (fixing the installment value, varying the disbursement) and disbursed_amount (fixing the disbursed value, varying the installment). When using disbursed_amount, provide the due dates in the due_dates array. The collateral_type field must be "vehicle". For simulation, the required fields in collateral_data are vehicle_type and license_state — fees vary per Detran region.

Response

STATUS
200
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
}
}
]
}
}

Installments Object

FieldDescription
calendar_daysCalendar days
business_due_dateBusiness day due date
due_dateDue date
due_principalDue principal
has_interestWhether the installment has interest
pre_fixed_amountPre-fixed installment amount
tax_amountTax amount
total_amountTotal installment amount
principal_amortization_amountPrincipal amortization amount
installment_numberInstallment number

Prefixed Interest Rate Object

FieldDescription
monthly_rateMonthly rate
daily_rateDaily rate
annual_rateAnnual rate
interest_baseInterest rate calculation base

Contract Fees Object

FieldTypeDescription
fee_typeStringFee type (e.g., registration_fee)
amount_typeStringValue type (absolute or percentage)
amountFloatMultiplier or percentage applied
fee_amountFloatFinal monetary fee amount
Registration Fees

General registration fees (DETRAN, SNG/B3) are reflected directly in the contract_fee_amount field within disbursement_options. The total fee amount is deducted from the issue amount (issue_amount), not from the net disbursement amount.


Operation Issuance

After simulating and validating the conditions, issue the credit operation with vehicle collateral. The request body includes the borrower data (natural person — the car buyer), financial data, vehicle collateral, and disbursement account.

The debt API is designed to be executed in a single request, after prior submission of files (document upload).

Borrower and Disbursement

The debt borrower (borrower) is the natural person buying the vehicle. The disbursement (disbursement_bank_accounts) is made to the dealership — meaning the bank account details provided should belong to the dealership selling the vehicle.

Document Upload

Before issuing the debt, upload the borrower's documents via POST /upload. Each document returns a UUID (document_key) that must be included in the borrower payload.

DocumentBorrower FieldDescriptionReq.
Identity document (front)document_identificationID card, driver's license or other photo ID (front)YES
Identity document (back)document_identification_backBack of the identity documentYES
Proof of residenceproof_of_residenceUpdated proof of addressYES
Document Upload

See the full upload documentation: Document Upload. Vehicle documents are not required.

Request

ENDPOINT
/debt
METHOD
POST
Test in Playground
Request Body
{
"borrower": {
"name": "João da Silva",
"email": "joao.silva@email.com",
"phone": {
"number": "999998888",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "100",
"street": "Rua Exemplo",
"complement": "Apto 42",
"postal_code": "01001000",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1990-01-15",
"mother_name": "MARIA DA SILVA",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"individual_document_number": "12345678901",
"document_identification": "<uuid-front>",
"document_identification_back": "<uuid-back>",
"proof_of_residence": "<uuid-proof>"
},
"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_data": {
"vehicle": {
"plate_state": "SP",
"renavan": "12345678901",
"vehicle_type": "car",
"model": "GOL 1.0",
"chassis": "9BWZZZ377VT004251",
"model_year": 2024,
"chassis_type": "normal",
"manufacturing_year": 2023,
"license_state": "SP",
"plate": "ABC1234"
},
"seller": {
"document_number": "37197645832",
"name": "Seller Test"
},
"credit_release_postal_code": "17057770"
},
"collateral_type": "vehicle"
}
],
"purchaser_document_number": "32402502000135",
"disbursement_bank_accounts": [
{
"name": "CONCESSIONARIA EXEMPLO VEICULOS",
"bank_code": "329",
"branch_number": "0001",
"account_number": "62400",
"account_digit": "6",
"document_number": "98765432000100",
"percentage_receivable": 100
}
]
}
Important

There is no need to call separate endpoints to register the lien or contract. Simply include the vehicle data in the collaterals object when creating the debt and QI Tech handles the entire process internally (lien inclusion at SNG/B3, contract registration at DETRAN/Registry, image submission).

reservation_method

After creation, the API automatically adds reservation_method to collateral_data (value: "creation" or "issuing" depending on requester configuration). This field should not be sent in the request.

Disbursement value (disbursed_amount)

POST /debt accepts either installment_face_value (fixes the installment value, varying the disbursement) or disbursed_amount (fixes the disbursed value, varying the installment) inside the financial object. The two fields are mutually exclusive. When using disbursed_amount, keep all other financial rules (rates, dates, number of installments) identical to the simulation payload.

Operation Modality (modality)

A vehicle collateral credit operation requires the partner to inform the operation modality according to the BACEN classification (Document 3040 / SCR). The modality is sent in the modality object at the root of the POST /debt payload and determines the operation's lien type and the disbursement rules applied when the debt is created.

modality at the root of POST /debt
{
"modality": {
"code": "0203"
}
}
FieldTypeDescriptionReq.
modality.codeString (4 digits)BACEN modality code (Doc 3040). See the supported modalities table below.YES
modality.enumeratorStringOptional modality enumerator. May be omitted or sent as null.NO
modality is required for vehicle collateral

If the modality is not sent (or the code is not supported), issuance is rejected with COP000539. Always send one of the codes from the table below.

Supported modalities

modality.codeBACEN modalityOperation typeDisbursement rule
0401Vehicle acquisitionPurchase (vehicle financing)Disbursement to the dealership/reseller (CNPJ document)
0203Personal credit without payroll deductionVehicle equity (refinancing / credit backed by the vehicle)Disbursement to the borrower
Operation type derived from the modality

QI Tech identifies the operation type from modality.code and stores the corresponding lien type in the reservation. Modality 0401 sets up a purchase (the credit pays the dealership); modality 0203 sets up a vehicle equity operation (the credit goes to the borrower). Any other code is rejected with COP000539.

Modality and disbursement validation errors

When the debt is created, the modality and the disbursement account are validated together. The errors below may be returned:

CodeHTTPMessage
COP000539400Bad Request
Unsupported credit modality for vehicle collateral.
Modalidade de crédito não suportada para garantia de veículo.
COP000540400Bad Request
Vehicle equity operations require the disbursement account document to match the borrower document.
Operações de vehicle equity exigem que o documento da conta de desembolso seja o mesmo do tomador.
COP000541400Bad Request
Vehicle purchase operations require the disbursement account document to be a CNPJ.
Operações de compra de veículo exigem que o documento da conta de desembolso seja um CNPJ.
Consistency between modality and disbursement account
  • Purchase (0401): the account in disbursement_bank_accounts must belong to the dealership/reseller and its document_number must be a CNPJ (14 digits) — otherwise issuance is rejected with COP000541.
  • Vehicle equity (0203): disbursement must go to the borrower. Disbursing to a document other than the borrower's is rejected with COP000540.

Insurance (vehicle_credit_insurance)

The Auto Credit product supports credit life insurance issued together with the debt. Insurance is signaled inside financial.rebates and the premium (2.75% over the issuance amount) is calculated automatically by QI Tech — the partner only needs to flag the contract with the correct fee_type and description.

financial.rebates — Auto insurance
{
"rebates": [
{
"fee_type": "insurance_premium_qi_gross_up",
"description": "vehicle_credit_insurance"
}
]
}
FieldValueDescription
fee_type"insurance_premium_qi_gross_up"Indicates that the insurance premium must be grossed-up into the operation amount by QI Tech.
description"vehicle_credit_insurance"Identifies the Auto Credit insurance product.
Premium calculation

The 2.75% rate over the issuance amount is applied by QI Tech at issuance time. You do not need to send amount or amount_type for this fee_type — flagging the contract is enough.

Guarantors (guarantors) — CCB signers

To add guarantor(s) who sign the CCB (jointly and severally liable for the debt), send the guarantors array at the root of the POST /debt payload — at the same level as borrower, financial and collaterals.

Each guarantors item is registered as a related party (related_party) with the guarantor role and becomes a signer of the contract: it signs the CCB together with the borrower, through the certifier configured for the requester (e.g., QI Sign). The main borrower stays in borrower (role issuer).

guarantors (root) ≠ additional_data.guarantors

They are different fields with different effects:

  • guarantors (root) → the guarantor signs the CCB (is a signer and becomes liable).
  • additional_data.guarantorsdisplay only in the CCB's Quadro III-A (does not generate a signature).

For a guarantor who is actually bound, use the root guarantors. If you only send it in additional_data, the guarantor is printed on the CCB but does not sign.

FieldTypeDescriptionReq.
guarantors[].person_typeString"natural" (individual) or "legal" (company)YES
guarantors[].nameStringGuarantor full nameYES
guarantors[].individual_document_numberStringCPF (11 digits, numbers only) — for individualsYES (natural)
guarantors[].birth_dateStringBirth date (YYYY-MM-DD). Required to sign — the certifier uses it for data enrichment/biometrics; without it the guarantor cannot sign.YES (natural)
guarantors[].is_pepBooleanPolitically Exposed PersonYES (natural)
guarantors[].addressObjectGuarantor address (same shape as borrower.address)YES
guarantors[].emailStringEmail — signing channel when signature_method = emailConditional
guarantors[].phoneObject{area_code, number, country_code} — channel when signature_method = sms/whatsapp (9-digit number)Conditional
guarantors[].mother_nameStringMother's name (used in signature enrichment)Recommended
Signing channel per guarantor

Each guarantor signs through the operation's signature_method. If email, the guarantor's email must be valid; if sms/whatsapp, the phone must be complete (area code + 9 digits). Without the matching channel, that guarantor's signature collection fails.

Spouse and attorney

A natural-person guarantor may carry:

  • spouse (person object): under a marital property regime that requires consent, the spouse is automatically added as a consenting party (intervening_consentor) and also signs.
  • attorney_list (array): attorney(s) signing on behalf of the guarantor (issuer_attorney).
guarantors at the root of POST /debt
{
"borrower": { "...": "borrower (role_type: issuer)" },
"guarantors": [
{
"person_type": "natural",
"name": "Maria da Silva",
"individual_document_number": "12345678901",
"birth_date": "1980-05-15",
"is_pep": false,
"email": "maria.guarantor@email.com",
"phone": { "area_code": "11", "number": "999999999", "country_code": "055" },
"address": {
"postal_code": "01310100", "street": "Rua Exemplo", "number": "100",
"neighborhood": "Centro", "city": "São Paulo", "state": "SP"
}
}
],
"financial": { "...": "..." },
"collaterals": [ { "collateral_type": "vehicle", "...": "..." } ]
}

Disbursement Payload Examples

The disbursement_bank_accounts field accepts different payment methods. The disbursement is made to the dealership:

{
"disbursement_bank_accounts": [
{
"document_number": "98765432000100",
"name": "CONCESSIONARIA EXEMPLO VEICULOS",
"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
"pix_transfer_type": "key",
"percentage_receivable": 100
}
]
}

Borrower Fields (Natural Person)

FieldTypeDescriptionReq.
nameStringBuyer's full nameYES
emailStringContact emailYES
phoneObjectContact phoneYES
is_pepBooleanPolitically exposed personYES
addressObjectBuyer's addressYES
role_typeStringBorrower role (issuer)YES
birth_dateStringDate of birth (YYYY-MM-DD)YES
mother_nameStringMother's nameYES
nationalityStringNationalityYES
person_typeStringAlways "natural"YES
marital_statusStringMarital status (single, married, divorced, widowed)YES
individual_document_numberStringBuyer's CPF (11 digits)YES
document_identificationStringUUID of the identity document (front), uploaded via /uploadYES
document_identification_backStringUUID of the identity document (back), uploaded via /uploadYES
proof_of_residenceStringUUID of the proof of residence, uploaded via /uploadYES

collateral_data Fields

FieldTypeDescriptionReq.
vehicleObjectVehicle dataYES
sellerObjectSeller dataYES
credit_release_postal_codeStringPostal code for credit release (8 digits)YES

vehicle Object

FieldTypeDescriptionReq.
vehicle_typeStringVehicle type (car, motorcycle, truck)YES
plateStringVehicle plateYES
plate_stateStringState of the vehicle plate (2 chars, uppercase)YES
license_stateStringVehicle licensing state (2 chars, uppercase)YES
renavanStringRENAVAN number (11 digits)YES
chassisStringVehicle chassis numberYES
chassis_typeStringChassis type (normal or remarcado)YES
modelStringVehicle modelYES
model_yearIntegerModel yearYES
manufacturing_yearIntegerManufacturing yearYES

seller Object

FieldTypeDescriptionReq.
nameStringDealership/seller nameYES
document_numberStringCPF (11 digits) or CNPJ (14 digits) of the sellerYES

Response

STATUS
201
Response Body
{
"webhook_type": "debt",
"key": "<Debt Key>",
"status": "waiting_signature",
"event_datetime": "2025-05-10 14:30:00",
"data": {
"borrower": {
"name": "João da Silva",
"document_number": "12345678901",
"related_party_key": "3571e292-3a83-4011-904d-20ee963022ef"
},
"contract": {
"number": "OP-000000000000001",
"urls": [
"https://storage.googleapis.com/doc-api/documents/<uuid>/JOAO_DA_SILVA-CCB-OP000000000000001.pdf"
],
"signature_information": [
{
"signer_name": "João da Silva",
"signer_document_number": "12345678901",
"signer_role": "issuer",
"signer_email": "joao.silva@email.com",
"signer_external_key": null,
"signature_url": null
}
]
},
"collaterals": [
{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"vehicle": {
"plate_state": "SP",
"renavan": "12345678901",
"vehicle_type": "car",
"model": "GOL 1.0",
"chassis": "9BWZZZ377VT004251",
"model_year": 2024,
"chassis_type": "normal",
"manufacturing_year": 2023,
"license_state": "SP",
"plate": "ABC1234"
},
"seller": {
"document_number": "37197645832",
"name": "Seller Test"
},
"credit_release_postal_code": "17057770"
},
"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"
}
}
]
}
}

Enumerators

collateral_type

ValueDescription
vehicleVehicle collateral (lien)

vehicle_type

ValueDescription
carCar
motorcycleMotorcycle
truckTruck

chassi_type

ValueDescription
RemarcadoRe-stamped chassis
NormalNormal chassis (default)

Cancellation

Cancellation flows for the operation (before disbursement, refund via /debt/reversal, or permanent cancellation) are documented on the dedicated page: Cancellation.

Other Available Actions

After issuing the debt, other functionalities are available in the debt API that can be used in conjunction with vehicle collateral operations:

ActionDescriptionDocumentation
Authorize disbursementAuthorize or block the disbursement of an operationAuthorize Disbursement
Update related party dataUpdate registration information (address, phone, email) of the parties related to the contractUpdate Related Party
Resend documentsResend documents of the parties related to the credit contractResend Documents
Bank account resubmissionUpdate bank details for disbursement after transfer errorBank Account Resubmission
Cancel debtCancel the operation before disbursementDebt Cancellation
Cancel permanentlyPermanently cancel the credit operationCancel Permanently
Dealership refundGenerate Pix QR Code for the dealership to refund the disbursed amount and release the lien/debt/reversal