Manual de Garantia Veicular

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma estrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

Este manual descreve o fluxo completo de uma operação de crédito com garantia veicular (gravame). O registro de gravame no SNG/B3, o registro do contrato no DETRAN/Registradora, o envio de imagem e o cancelamento são realizados internamente pela QI Tech. Você acompanha o processo via endpoints de consulta (GET) e webhooks.

Pré-requisitos

Possuir credenciais de acesso à API QI Tech (veja Primeiros Passos);
Ter concluído a homologação em ambiente sandbox;
Veículo deve possuir informações válidas de chassi, RENAVAM (quando já emplacado) e UF de licenciamento.

Visão Geral do Fluxo

Simulação — Simule a operação via POST /debt_simulation para obter condições financeiras;
Emissão — Crie a operação via POST /debt incluindo os dados do veículo no objeto collaterals;
Processamento Interno — A QI Tech processa automaticamente a inclusão de gravame no SNG/B3 e o registro do contrato no DETRAN/Registradora;
Acompanhamento — Consulte o status via endpoints GET e receba notificações via webhooks;
Conclusão — O processo finaliza quando todas as etapas (gravame, contrato, imagem) são completadas com sucesso.

URLs Base

Homologação: Fornecida pela QI Tech durante o onboarding.
Produção: Fornecida pela QI Tech após homologação.

Códigos HTTP

200 = Sucesso · 201 = Criado · 400 = Falha na validação (ver body) · 401 = Não autorizado · 403 = Requisição indevida · 404 = Não encontrado · 500 = Erro interno

1 - Simulação da dívida

Antes de emitir a operação, é possível simular as condições financeiras enviando os dados básicos com o tipo de garantia 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"
        }
    ]
}

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

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

2 - 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.

Os campos do veículo e da operação de garantia são enviados dentro do objeto collateral_data no array collaterals. A referência completa dos campos está em Campos da Garantia Veicular.

Request

POST

/debt

Request 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": "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": "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

Você não precisa 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).

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

Objeto Installments

Campo	Descrição
business_due_date	Data de vencimento em dia útil
calendar_days	Dias corridos
due_date	Data de vencimento
due_principal	Principal do vencimento
has_interest	Indica se o vencimento possui juros
installment_number	Número da parcela
pre_fixed_amount	Valor pré-fixado da parcela
principal_amortization_amount	Valor da amortização do principal
tax_amount	Valor de imposto da parcela
total_amount	Valor total da parcela
installment_status	Status da parcela
installment_type	Tipo de parcela

Webhooks

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

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

Objeto Data

Campo	Descrição
cancel_reason	Motivo do cancelamento
cancel_reason_enumerator	Enumerador do motivo do cancelamento

3 - Acompanhamento — Consultas

Após a emissão da operação, a QI Tech processa internamente as etapas de gravame, contrato e imagem. Você acompanha o progresso via os endpoints de consulta abaixo utilizando o codigoQiTech.

3.1 - Consultar Status Atual

ENDPOINT

/v1/vehicles/contracts/status/

MÉTODO

GET

Request Params

Campo	Tipo	Descrição	Obrig.
codigoQiTech	String	Identificador único do pedido (até 255 caracteres)	SIM

Response Body (200)

Campo	Tipo	Descrição
codigoQiTech	String	Identificador único do pedido
etapaAtual	String	Etapa do processo (Inclusão de Gravame / Registro do Contrato / Aditivo do Contrato / Imagem de Contrato)
status	String	Status atual do processo (ver seção 5 - Mapa de Status)
msgRetornoProvedor	String	Mensagem de retorno do provedor (populado em caso de negativa)
msgRetornoPlataforma	String	Mensagem de retorno da plataforma (populado em caso de negativa)
dataUltimaAtualizacao	String	Data da última atualização (YYYY-MM-DD)
chassi	String	Chassi do veículo
ufDeLicenciamento	String	UF licenciamento do veículo
numGravame	String	Número do gravame (até 8 chars; "0" se ainda não houver)

3.2 - Consultar Histórico

ENDPOINT

/v1/vehicles/contracts/history/

MÉTODO

GET

Request Params

Campo	Tipo	Descrição	Obrig.
codigoQiTech	String	Identificador único do pedido (até 255 caracteres)	SIM

Response Body (200)

Campo	Tipo	Descrição
codigoQiTech	String	Identificador único do pedido
historicoGarantia	String	Descritivo das operações realizadas com data/hora de cada
msgRetornoProvedor	String	Mensagem de retorno do provedor
msgRetornoPlataforma	String	Mensagem de retorno da plataforma
chassi	String	Chassi do veículo
ufDeLicenciamento	String	UF licenciamento
numGravame	String	Número do gravame (até 8 caracteres)

Informação

Nos retornos "Negado", "Dados Inválidos" ou "Inválida", pelo menos um dos campos msgRetornoPlataforma e msgRetornoProvedor estará populado com o motivo.

4 - Webhooks — Garantia Veicular

Notificações assíncronas enviadas via POST pela QI Tech para informar sobre mudanças de status nas etapas de gravame, contrato e imagem. A requisição deve ser respondida em até 10 segundos com HTTP 200.

Webhook de Status do Pedido

Payload

Campo	Tipo	Descrição
transactionId	String	ID da transação (36 chars)
status	String	Status do pedido (ver seção 5)
msgRetornoPlataforma	String	Mensagem de retorno da plataforma
codigoQiTech	String	Identificador único do pedido
etapaAtual	String	Etapa atual (Inclusão de Gravame / Registro do Contrato / Aditivo do Contrato / Imagem de Contrato)
timestamp	DATETIME	Momento do envio
dataUltimaAtualizacao	DATETIME	Data da atualização na plataforma
gravame	String	Número do gravame ("0" quando não houver)
uf	String	UF onde gravame foi criado (2 chars)
chassi	String	Chassi do veículo

Atenção

O status "Em Processamento" não é enviado via webhook para as etapas Registro do Contrato, Inclusão de Gravame e Aditivo de Contrato.

Configuração

O Webhook de Status requer URLs cadastradas + seleção de etapas/status desejados. Consulte o time de onboarding para configurar.

5 - Mapa de Status e Etapas

5.1 - Inclusão de Gravame

Status	Descrição
Em Processamento	Dados inseridos na plataforma, em processo de registro no SNG da B3
Enviado	Dados enviados com sucesso ao SNG. Aguardando retorno
Registrado	Inclusão de gravame realizada com sucesso no SNG
Dados Inválidos	Retorno do SNG indicando erro nos dados enviados
Negado	Retorno do SNG indicando impedimento ou restrição
Cancelado	Solicitação cancelada na plataforma

5.2 - Registro do Contrato / Aditivo do Contrato

Status	Descrição
Em Processamento	Dados inseridos na plataforma, em processo junto ao DETRAN ou Registradora
Enviado	Dados enviados com sucesso. Aguardando aprovação/pagamento da taxa
A Confirmar	Aguardando confirmação
Registrado	Registro realizado com sucesso
Dados Inválidos	DETRAN indica erro nos dados enviados
Negado	DETRAN gerou negativa para o registro
Cancelado	Contrato cancelado na plataforma
Balcão Detran	DF e TO: devedor deve comparecer ao DETRAN fisicamente
UF sem Registro	Exclusivo AL: não existe registro de contrato
Finalizado	Gravame financeiro do veículo não está mais ativo

5.3 - Imagem de Contrato

Status	Descrição
Anexada	Imagem anexada na plataforma
Enviada	Imagem enviada com sucesso para DETRAN/Registradora
Aprovada	Imagem aprovada pelo DETRAN
Negada	DETRAN negou a imagem (ex: falta assinatura, baixa qualidade)
Inválida	DETRAN indica imagem inválida (ex: enviada após cancelamento)

Enumeradores

collateral_type

Valor	Descrição
car_collateral	Garantia veicular (gravame)

chassi_type

Valor	Descrição
Remarcado	Chassi remarcado
Normal	Chassi normal (padrão)

Pré-requisitos​

Visão Geral do Fluxo​

1 - Simulação da dívida​

Request​

Response​

Objeto Installments​

Objeto Prefixed Interest Rate​

2 - Emissão da operação​

Request​

Response​

Objeto Installments​

Webhooks​

Objeto Data​

3 - Acompanhamento — Consultas​

3.1 - Consultar Status Atual​

3.2 - Consultar Histórico​

4 - Webhooks — Garantia Veicular​

Webhook de Status do Pedido​

5 - Mapa de Status e Etapas​

5.1 - Inclusão de Gravame​

5.2 - Registro do Contrato / Aditivo do Contrato​

5.3 - Imagem de Contrato​

Enumeradores​

collateral_type​

chassi_type​

Pré-requisitos

Visão Geral do Fluxo

1 - Simulação da dívida

Request

Response

Objeto Installments

Objeto Prefixed Interest Rate

2 - Emissão da operação

Request

Response

Objeto Installments

Webhooks

Objeto Data

3 - Acompanhamento — Consultas

3.1 - Consultar Status Atual

3.2 - Consultar Histórico

4 - Webhooks — Garantia Veicular

Webhook de Status do Pedido

5 - Mapa de Status e Etapas

5.1 - Inclusão de Gravame

5.2 - Registro do Contrato / Aditivo do Contrato

5.3 - Imagem de Contrato

Enumeradores

collateral_type

chassi_type