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

Installment value with disbursement amount
Disbursement value with rate

{
    "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"
            }
        }
    ]
}

{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2025-05-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "monthly_interest_rate": 0.018,
        "disbursed_amount": 10000.00,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 12,
        "principal_grace_period": 0,
        "due_dates": [
            "2025-06-15",
            "2025-07-15",
            "2025-08-15",
            "2025-09-15",
            "2025-10-15",
            "2025-11-15",
            "2025-12-15",
            "2026-01-15",
            "2026-02-15",
            "2026-03-15",
            "2026-04-15",
            "2026-05-15"
        ]
    },
    "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

Field	Description
calendar_days	Calendar days
business_due_date	Business day due date
due_date	Due date
due_principal	Due principal
has_interest	Whether the installment has interest
pre_fixed_amount	Pre-fixed installment amount
tax_amount	Tax amount
total_amount	Total installment amount
principal_amortization_amount	Principal amortization amount
installment_number	Installment number

Prefixed Interest Rate Object

Field	Description
monthly_rate	Monthly rate
daily_rate	Daily rate
annual_rate	Annual rate
interest_base	Interest rate calculation base

Contract Fees Object

Field	Type	Description
fee_type	String	Fee type (e.g., `registration_fee`)
amount_type	String	Value type (`absolute` or `percentage`)
amount	Float	Multiplier or percentage applied
fee_amount	Float	Final 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.

Document	Borrower Field	Description	Req.
Identity document (front)	`document_identification`	ID card, driver's license or other photo ID (front)	YES
Identity document (back)	`document_identification_back`	Back of the identity document	YES
Proof of residence	`proof_of_residence`	Updated proof of address	YES

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 Payload Examples

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

Pix (key)
Pix (manual)
TED
QR Code Pix
Boleto

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

{
    "disbursement_bank_accounts": [
        {
            "document_number": "98765432000100",
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "pix_transfer_type": "manual",
            "bank_code": "329",
            "branch_number": "0001",
            "account_number": "62400",
            "account_digit": "6",
            "percentage_receivable": 100
        }
    ]
}

{
    "disbursement_bank_accounts": [
        {
            "transfer_method": "ted",
            "bank_code": "341",
            "branch_number": "8615",
            "account_number": "22110",
            "account_digit": "2",
            "document_number": "98765432000100",
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "percentage_receivable": 100
        }
    ]
}

{
    "disbursement_bank_accounts": [
        {
            "qr_code_key": "b76e436e-4767-4b16-91e6-9bfc794f2510"
        }
    ]
}

{
    "disbursement_bank_accounts": [
        {
            "digitable_line": "836400000169072200500006763953020230059001020193",
            "amount_receivable": 1607.22
        }
    ]
}

Borrower Fields (Natural Person)

Field	Type	Description	Req.
name	String	Buyer's full name	YES
email	String	Contact email	YES
phone	Object	Contact phone	YES
is_pep	Boolean	Politically exposed person	YES
address	Object	Buyer's address	YES
role_type	String	Borrower role (`issuer`)	YES
birth_date	String	Date of birth (YYYY-MM-DD)	YES
mother_name	String	Mother's name	YES
nationality	String	Nationality	YES
person_type	String	Always `"natural"`	YES
marital_status	String	Marital status (`single`, `married`, `divorced`, `widowed`)	YES
individual_document_number	String	Buyer's CPF (11 digits)	YES
document_identification	String	UUID of the identity document (front), uploaded via `/upload`	YES
document_identification_back	String	UUID of the identity document (back), uploaded via `/upload`	YES
proof_of_residence	String	UUID of the proof of residence, uploaded via `/upload`	YES

collateral_data Fields

Field	Type	Description	Req.
vehicle	Object	Vehicle data	YES
seller	Object	Seller data	YES
credit_release_postal_code	String	Postal code for credit release (8 digits)	YES

vehicle Object

Field	Type	Description	Req.
vehicle_type	String	Vehicle type (`car`, `motorcycle`, `truck`)	YES
plate	String	Vehicle plate	YES
plate_state	String	State of the vehicle plate (2 chars, uppercase)	YES
license_state	String	Vehicle licensing state (2 chars, uppercase)	YES
renavan	String	RENAVAN number (11 digits)	YES
chassis	String	Vehicle chassis number	YES
chassis_type	String	Chassis type (`normal` or `remarcado`)	YES
model	String	Vehicle model	YES
model_year	Integer	Model year	YES
manufacturing_year	Integer	Manufacturing year	YES

seller Object

Field	Type	Description	Req.
name	String	Dealership/seller name	YES
document_number	String	CPF (11 digits) or CNPJ (14 digits) of the seller	YES

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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "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

Value	Description
vehicle	Vehicle collateral (lien)

vehicle_type

Value	Description
car	Car
motorcycle	Motorcycle
truck	Truck

chassi_type

Value	Description
Remarcado	Re-stamped chassis
Normal	Normal chassis (default)

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:

Action	Description	Documentation
Authorize disbursement	Authorize or block the disbursement of an operation	Authorize Disbursement
Update related party data	Update registration information (address, phone, email) of the parties related to the contract	Update Related Party
Resend documents	Resend documents of the parties related to the credit contract	Resend Documents
Bank account resubmission	Update bank details for disbursement after transfer error	Bank Account Resubmission
Cancel debt	Cancel the operation before disbursement	Debt Cancellation
Cancel permanently	Permanently cancel the credit operation	Cancel Permanently

Debt Simulation​

Request​

Response​

Installments Object​

Prefixed Interest Rate Object​

Contract Fees Object​

Operation Issuance​

Document Upload​

Request​

Disbursement Payload Examples​

Borrower Fields (Natural Person)​

collateral_data Fields​

vehicle Object​

seller Object​

Response​

Enumerators​

collateral_type​

vehicle_type​

chassi_type​

Other Available Actions​

Debt Simulation

Request

Response

Installments Object

Prefixed Interest Rate Object

Contract Fees Object

Operation Issuance

Document Upload

Request

Disbursement Payload Examples

Borrower Fields (Natural Person)

collateral_data Fields

vehicle Object

seller Object

Response

Enumerators

collateral_type

vehicle_type

chassi_type

Other Available Actions