Vehicle Collateral Manual

Warning!

QI Tech webhooks should not be mapped restrictively. Additional fields may be included in the webhook payloads returned by our APIs.

Webhook Resend

You can query and resend webhooks following the detailed instructions in the documentation: Webhook Resend.

This manual describes the complete flow of a credit operation with vehicle collateral (lien). Lien registration at SNG/B3, contract registration at DETRAN/Registrar, image submission, and cancellation are all handled internally by QI Tech. You track the process via consultation (GET) endpoints and webhooks.

Prerequisites

Have access credentials for the QI Tech API (see Getting Started);
Have completed sandbox environment homologation;
The vehicle must have valid chassis, RENAVAM (when already licensed), and licensing state information.

Flow Overview

Simulation — Simulate the operation via POST /debt_simulation to obtain financial conditions;
Issuance — Create the operation via POST /debt including vehicle data in the collaterals object;
Internal Processing — QI Tech automatically processes lien registration at SNG/B3 and contract registration at DETRAN/Registrar;
Tracking — Query status via GET endpoints and receive notifications via webhooks;
Completion — The process finishes when all stages (lien, contract, image) are successfully completed.

Base URLs

Staging: Provided by QI Tech during onboarding.
Production: Provided by QI Tech after homologation.

HTTP Codes

200 = Success · 201 = Created · 400 = Validation failure (see body) · 401 = Unauthorized · 403 = Forbidden · 404 = Not found · 500 = Internal error

1 - Debt Simulation

Before issuing the operation, you can simulate the financial conditions by sending the basic data with collateral type car_collateral.

Request

POST

/debt_simulation

Request 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": "car_collateral"
        }
    ]
}

info

The simulation accepts both installment_face_value (fixing the installment amount, varying the disbursement) and disbursed_amount (fixing the disbursed amount, varying the installment). The collateral_type field must be "car_collateral".

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": [],
                "external_contract_fees": [],
                "contract_fee_amount": 0.0,
                "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": 5394.05,
                "assignment_amount": 5419.55,
                "final_disbursement_amount": 5394.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	Indicates whether the installment has interest
pre_fixed_amount	Pre-fixed installment amount
tax_amount	Tax amount of the installment
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

2 - Operation Issuance

After simulating and validating the conditions, issue the credit operation with vehicle collateral. The request body includes borrower data, financial data, vehicle collateral, and the disbursement account.

Vehicle and collateral operation fields are sent inside the collateral_data object in the collaterals array. The complete field reference is at Vehicle Collateral Fields.

Request

POST

/debt

Request Body
{
    "borrower": {
        "name": "Borrower Name",
        "email": "borrower@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": "Example Street",
            "complement": "Apt 10",
            "postal_code": "01001000",
            "neighborhood": "Centro"
        },
        "role_type": "issuer",
        "birth_date": "1990-01-15",
        "mother_name": "MOTHER NAME",
        "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": "car_collateral",
            "collateral_data": {
                "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": "BORROWER NAME",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "1234",
            "account_number": "000012345",
            "document_number": "12345678901",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}

Important

You do not need to call separate endpoints to register liens or contracts. Simply send the vehicle data in the collaterals object when creating the debt and QI Tech handles the entire process internally (lien registration at SNG/B3, contract registration at DETRAN/Registrar, image submission).

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": "Borrower Name",
            "document_number": "12345678901",
            "related_party_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/BORROWER_NAME-CCB-OP000000000000001.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Borrower Name",
                    "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": {
                    "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": "car_collateral",
                "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": [],
                "external_contract_fees": [],
                "contract_fee_amount": 0.0,
                "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"
                }
            }
        ]
    }
}

Installments Object

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

Webhooks

If the operation is not signed or endorsed by the last disbursement date option, the partner will receive a webhook notifying about the operation cancellation:

WEBHOOK TYPE

debt

STATUS

Canceled

Webhook 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>"
    }
}

Data Object

Field	Description
cancel_reason	Cancellation reason
cancel_reason_enumerator	Cancellation reason enumerator

3 - Tracking — Queries

After the operation is issued, QI Tech internally processes the lien, contract, and image stages. You track the progress via the consultation endpoints below using the codigoQiTech.

3.1 - Query Current Status

ENDPOINT

/v1/vehicles/contracts/status/

METHOD

GET

Request Params

Field	Type	Description	Req.
codigoQiTech	String	Unique order identifier (up to 255 characters)	YES

Response Body (200)

Field	Type	Description
codigoQiTech	String	Unique order identifier
etapaAtual	String	Process stage (Lien Registration / Contract Registration / Contract Addendum / Contract Image)
status	String	Current process status (see section 5 - Status Map)
msgRetornoProvedor	String	Provider return message (populated on rejection)
msgRetornoPlataforma	String	Platform return message (populated on rejection)
dataUltimaAtualizacao	String	Last update date (YYYY-MM-DD)
chassi	String	Vehicle chassis
ufDeLicenciamento	String	Vehicle licensing state
numGravame	String	Lien number (up to 8 chars; "0" if not yet available)

3.2 - Query History

ENDPOINT

/v1/vehicles/contracts/history/

METHOD

GET

Request Params

Field	Type	Description	Req.
codigoQiTech	String	Unique order identifier (up to 255 characters)	YES

Response Body (200)

Field	Type	Description
codigoQiTech	String	Unique order identifier
historicoGarantia	String	Operation history with date/time of each event
msgRetornoProvedor	String	Provider return message
msgRetornoPlataforma	String	Platform return message
chassi	String	Vehicle chassis
ufDeLicenciamento	String	Licensing state
numGravame	String	Lien number (up to 8 characters)

Information

On "Denied", "Invalid Data", or "Invalid" responses, at least one of the fields msgRetornoPlataforma and msgRetornoProvedor will be populated with the reason.

4 - Webhooks — Vehicle Collateral

Asynchronous notifications sent via POST by QI Tech to report status changes in the lien, contract, and image stages. The request must be answered within 10 seconds with HTTP 200.

Order Status Webhook

Payload

Field	Type	Description
transactionId	String	Transaction ID (36 chars)
status	String	Order status (see section 5)
msgRetornoPlataforma	String	Platform return message
codigoQiTech	String	Unique order identifier
etapaAtual	String	Current stage (Lien Registration / Contract Registration / Contract Addendum / Contract Image)
timestamp	DATETIME	Send timestamp
dataUltimaAtualizacao	DATETIME	Platform update date
gravame	String	Lien number ("0" when not available)
uf	String	State where lien was created (2 chars)
chassi	String	Vehicle chassis

Attention

The status "Processing" is not sent via webhook for the stages Contract Registration, Lien Registration, and Contract Addendum.

Configuration

The Status Webhook requires registered URLs + selection of desired stages/statuses. Consult the onboarding team for configuration.

5 - Status and Stage Map

5.1 - Lien Registration

Status	Description
Processing	Data inserted on the platform, being registered at B3's SNG
Sent	Data successfully sent to SNG. Awaiting response
Registered	Lien successfully registered at SNG
Invalid Data	SNG response indicating data error
Denied	SNG response indicating impediment or restriction
Cancelled	Request cancelled on the platform

5.2 - Contract Registration / Contract Addendum

Status	Description
Processing	Data inserted on the platform, being processed by DETRAN or Registrar
Sent	Data successfully sent. Awaiting approval/fee payment
To Confirm	Awaiting confirmation
Registered	Registration successful
Invalid Data	DETRAN indicates data error
Denied	DETRAN denied the registration
Cancelled	Contract cancelled on the platform
DETRAN Counter	DF and TO: debtor must physically go to DETRAN
Unregistered State	AL only: no contract registration exists
Finalized	Vehicle financial lien is no longer active

5.3 - Contract Image

Status	Description
Attached	Image attached on the platform
Sent	Image successfully sent to DETRAN/Registrar
Approved	Image approved by DETRAN
Denied	DETRAN denied the image (e.g., missing signature, low quality)
Invalid	DETRAN indicates invalid image (e.g., sent after cancellation)

Enumerators

collateral_type

Value	Description
car_collateral	Vehicle collateral (lien)

chassi_type

Value	Description
Remarcado	Remarked chassis
Normal	Normal chassis (default)

Prerequisites​

Flow Overview​

1 - Debt Simulation​

Request​

Response​

Installments Object​

Prefixed Interest Rate Object​

2 - Operation Issuance​

Request​

Response​

Installments Object​

Webhooks​

Data Object​

3 - Tracking — Queries​

3.1 - Query Current Status​

3.2 - Query History​

4 - Webhooks — Vehicle Collateral​

Order Status Webhook​

5 - Status and Stage Map​

5.1 - Lien Registration​

5.2 - Contract Registration / Contract Addendum​

5.3 - Contract Image​

Enumerators​

collateral_type​

chassi_type​

Prerequisites

Flow Overview

1 - Debt Simulation

Request

Response

Installments Object

Prefixed Interest Rate Object

2 - Operation Issuance

Request

Response

Installments Object

Webhooks

Data Object

3 - Tracking — Queries

3.1 - Query Current Status

3.2 - Query History

4 - Webhooks — Vehicle Collateral

Order Status Webhook

5 - Status and Stage Map

5.1 - Lien Registration

5.2 - Contract Registration / Contract Addendum

5.3 - Contract Image

Enumerators

collateral_type

chassi_type