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

ENDPOINT

/debt_simulation

MÉTODO

POST

Testar no Playground

Request Body

Valor de desembolso com taxa
Valor de parcela com valor de desembolso

{
    "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"]
    },
    "collaterals": [
        {
            "collateral_type": "vehicle",
            "collateral_data": {
                "vehicle": {
                    "vehicle_type": "automobile",
                    "license_state": "SP"
                }
            }
        }
    ]
}

{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2025-06-15",
        "installment_face_value": 500,
        "disbursed_amount": 5000.00,
        "disbursement_date": "2025-05-10",
        "limit_days_to_disburse": 3,
        "number_of_installments": 12,
        "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": {
                    "vehicle_type": "automobile",
                    "license_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). Ao usar disbursed_amount, informe as datas de vencimento no array due_dates. O campo collateral_type deve ser "vehicle". Para simulação, os campos obrigatórios em collateral_data são vehicle_type e license_state — as taxas variam por região do Detran.

Response

STATUS

200

Response Body

{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2025-05-10 03:18:18",
    "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.2387205316,
            "monthly_rate": 0.018,
            "daily_rate": 0.0005866899
        },
        "issue_date": "2025-05-10",
        "number_of_installments": 1,
        "final_disbursement_amount": 10000.00,
        "total_pre_fixed_amount": 195.25,
        "iof_amount": 67.49,
        "cet": 0.082,
        "annual_cet": 1.575,
        "disbursement_date": "2025-05-10",
        "installments": [
            {
                "calendar_days": 31,
                "workdays": 22,
                "business_due_date": "2025-06-10",
                "due_date": "2025-06-10",
                "due_principal": 10641.24,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 195.25,
                "tax_amount": 27.05,
                "total_amount": 10836.49,
                "principal_amortization_amount": 10641.24,
                "installment_number": 1
            }
        ],
        "external_contract_fees": [],
        "contract_fee_amount": 605.67,
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 0.3,
                "fee_amount": 31.92
            },
            {
                "fee_type": "tac_vehicle_fee",
                "amount_type": "absolute",
                "amount": 573.75,
                "fee_amount": 573.75
            }
        ],
        "issue_amount": 10641.24,
        "disbursed_issue_amount": 10000.00,
        "assignment_amount": 10673.16,
        "disbursement_options": [
            {
                "iof_amount": 67.49,
                "total_pre_fixed_amount": 195.25,
                "cet": 0.082,
                "annual_cet": 1.575,
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "percentage",
                        "amount": 0.3,
                        "fee_amount": 31.92
                    },
                    {
                        "fee_type": "tac_vehicle_fee",
                        "amount_type": "absolute",
                        "amount": 573.75,
                        "fee_amount": 573.75
                    }
                ],
                "external_contract_fees": [],
                "contract_fee_amount": 605.67,
                "external_contract_fee_amount": 0,
                "net_external_contract_fee_amount": 0,
                "disbursement_date": "2025-05-10",
                "first_due_date": "2025-06-10",
                "installments": [
                    {
                        "calendar_days": 31,
                        "workdays": 22,
                        "business_due_date": "2025-06-10",
                        "due_date": "2025-06-10",
                        "due_principal": 10641.24,
                        "has_interest": true,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 195.25,
                        "tax_amount": 27.05,
                        "total_amount": 10836.49,
                        "principal_amortization_amount": 10641.24,
                        "installment_number": 1
                    }
                ],
                "issue_amount": 10641.24,
                "disbursed_issue_amount": 10000.00,
                "assignment_amount": 10673.16,
                "final_disbursement_amount": 10000.00,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.2387205316,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.0005866899
                }
            }
        ]
    }
}

Objeto Installments

Campo	Descrição
calendar_days	Dias corridos
workdays	Dias úteis
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
post_fixed_amount	Valor pós-fixado da parcela
tax_amount	Valor de IOF 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 (ver tabela abaixo)
amount_type	String	Tipo de valor: `absolute` (valor fixo) ou `percentage` (percentual sobre o desembolso)
amount	Float	Valor da taxa: multiplicador (se `percentage`) ou valor fixo (se `absolute`)
fee_amount	Float	Valor monetário final da taxa cobrada

Tipos de fee (fee_type)

Valor	Descrição
`tac_vehicle_fee`	Custos de gravame e registro no DETRAN — variam por estado (UF de licenciamento do veículo). Inclui taxas do SNG/B3 e da Registradora.
`spread`	Spread da operação, calculado como percentual sobre o valor desembolsado.

Contract Fees na Garantia Veicular

O campo contract_fees retornado na simulação pode conter uma combinação de tac_vehicle_fee e/ou spread. O tac_vehicle_fee corresponde aos custos de gravame (SNG/B3) e registro de contrato (DETRAN/Registradora), que variam por estado conforme o UF de licenciamento informado em license_state. O total de todas as taxas é somado em contract_fee_amount.

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 (pessoa física — comprador do veículo), dados financeiros, garantia veicular e conta para desembolso.

A API de dívida foi desenhada para ser executada em apenas uma requisição, após um prévio envio dos arquivos (upload de documentos).

Tomador e Desembolso

O tomador da dívida (borrower) é a pessoa física que está comprando o veículo. O desembolso (disbursement_bank_accounts) é realizado para a concessionária ou revenda de veículos — ou seja, os dados bancários informados devem ser da concessionária que está vendendo o veículo.

Envio de Documentos

Antes de emitir a dívida, envie os documentos do tomador via POST /upload. Cada documento retorna um UUID (document_key) que deve ser incluído no payload do borrower.

Documento	Campo no borrower	Descrição	Obrig.
Documento de identidade (frente)	`document_identification`	RG, CNH ou outro documento com foto (frente)	SIM
Documento de identidade (verso)	`document_identification_back`	Verso do documento de identidade	SIM
Comprovante de residência	`proof_of_residence`	Comprovante de endereço atualizado	SIM

Upload de Documentos

Consulte a documentação completa de upload: Upload de Documentos. Não é necessário enviar documentos do veículo.

Request

ENDPOINT

/debt

MÉTODO

POST

Testar no 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-frente>",
        "document_identification_back": "<uuid-verso>",
        "proof_of_residence": "<uuid-comprovante>"
    },
    "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",
                    "renavam": "12345678901",
                    "vehicle_type": "automobile",
                    "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
        }
    ]
}

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

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.

Rebate

É possível informar rebates no POST /debt, permitindo ao parceiro repassar ao tomador descontos sobre as taxas da operação. O campo é um array de objetos, cada um com:

Campo	Tipo	Descrição
`fee_type`	String	Tipo da taxa: `"tac"` (Tarifa de Abertura de Crédito) ou `"insurance_premium"` (prêmio de seguro)
`amount`	Float	Valor do desconto
`amount_type`	String	Tipo do valor: `"absolute"` (valor fixo) ou `"percentage"` (percentual)
`rebate_bank_account`	Object	Conta bancária destinatária do rebate

{
    "rebates": [
        {
            "amount": 100.00,
            "fee_type": "tac",
            "amount_type": "absolute",
            "rebate_bank_account": {
                "name": "CONCESSIONARIA EXEMPLO VEICULOS",
                "bank_code": "329",
                "account_digit": "1",
                "branch_number": "0001",
                "account_number": "00003",
                "document_number": "32402502000135"
            }
        }
    ]
}

Exemplos de payload de desembolso

O campo disbursement_bank_accounts aceita diferentes métodos de pagamento. O desembolso é realizado para a concessionária/revenda:

Pix (chave)
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
        }
    ]
}

Campos do borrower (Pessoa Física)

Campo	Tipo	Descrição	Obrig.
name	String	Nome completo do comprador	SIM
email	String	E-mail de contato	SIM
phone	Object	Telefone de contato	SIM
is_pep	Boolean	Pessoa politicamente exposta	SIM
address	Object	Endereço do comprador	SIM
role_type	String	Papel do tomador (`issuer`)	SIM
birth_date	String	Data de nascimento (YYYY-MM-DD)	SIM
mother_name	String	Nome da mãe	SIM
nationality	String	Nacionalidade	SIM
person_type	String	Sempre `"natural"`	SIM
marital_status	String	Estado civil (`single`, `married`, `divorced`, `widowed`)	SIM
individual_document_number	String	CPF do comprador (11 dígitos)	SIM
document_identification	String	UUID do documento de identidade (frente), enviado via `/upload`	SIM
document_identification_back	String	UUID do documento de identidade (verso), enviado via `/upload`	SIM
proof_of_residence	String	UUID do comprovante de residência, enviado via `/upload`	SIM

Campos do collateral_data

Campo	Tipo	Descrição	Obrig.
vehicle	Object	Dados do veículo	SIM
seller	Object	Dados do vendedor	SIM
credit_release_postal_code	String	CEP para liberação de crédito (8 dígitos)	SIM

Objeto vehicle

Campo	Tipo	Descrição	Obrig.
vehicle_type	String	Tipo de veículo (ver Enumeradores)	SIM
plate	String	Placa do veículo	SIM
plate_state	String	UF da placa do veículo (2 chars, caixa alta)	SIM
license_state	String	UF de licenciamento do veículo (2 chars, caixa alta)	SIM
renavam	String	Número do RENAVAM (11 dígitos)	SIM
chassis	String	Número do chassi do veículo	SIM
chassis_type	String	Tipo de chassi (`normal` ou `remarcado`)	SIM
model	String	Modelo do veículo	SIM
model_year	Integer	Ano do modelo	SIM
manufacturing_year	Integer	Ano de fabricação	SIM

Objeto seller

Campo	Tipo	Descrição	Obrig.
name	String	Nome da concessionária/vendedor	SIM
document_number	String	CPF (11 dígitos) ou CNPJ (14 dígitos) do vendedor	SIM

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",
                        "renavam": "12345678901",
                        "vehicle_type": "automobile",
                        "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"
                }
            }
        ]
    }
}

Enumeradores

collateral_type

Valor	Descrição
vehicle	Garantia veicular (gravame)

vehicle_type

Valor	Descrição
automobile	Automóvel
moped	Ciclomotor
scooter	Scooter
motorcycle	Motocicleta
tricycle	Triciclo
minibus	Micro-ônibus
bus	Ônibus
trailer	Reboque
semi-trailer	Semirreboque
suv	SUV
truck	Caminhão
semi-truck	Caminhão-trator
wheel-tractor	Trator de rodas
crawler-tractor	Trator de esteira
mixed-type-tractor	Trator misto
quad-bike	Quadriciclo
platform-chassis	Chassi plataforma
pickup-truck	Camionete
utility-vehicle	Utilitário
motorhome	Motorhome
attachments	Implementos

chassi_type

Valor	Descrição
remarked	Chassi remarcado
normal	Chassi normal (padrão)

Atualização de Dados do Colateral Veicular

API em desenvolvimento

Este endpoint está em fase de desenvolvimento, sendo assim, sujeito a alterações.

Permite corrigir os dados do colateral veicular em caso de falha no registro do gravame. Utilize o endpoint abaixo para reenviar os dados corrigidos do veículo:

ENDPOINT

/debt/DEBT-KEY/vehicle_collateral/reservation

MÉTODO

PATCH

Request Body

{
    "collateral_data": {
        "vehicle": {
            "chassis": "9BWZZZ377VT004251",
            "chassis_type": "normal",
            "renavam": "12345678901",
            "plate": "ABC1234",
            "plate_state": "SP",
            "license_state": "SP",
            "vehicle_type": "automobile",
            "model": "GOL 1.0",
            "model_year": 2024,
            "manufacturing_year": 2023
        }
    }
}

Outras ações disponíveis

Após a emissão da dívida, existem outras funcionalidades disponíveis na API de dívidas que podem ser utilizadas em conjunto com operações de garantia veicular:

Ação	Descrição	Documentação
Autorizar desembolso	Autorizar ou bloquear o desembolso de uma operação	Autorizar Desembolso
Atualizar dados da parte relacionada	Atualizar informações cadastrais (endereço, telefone, e-mail) das partes relacionadas ao contrato	Atualizar Parte Relacionada
Reenviar documentos	Reenviar documentos das partes relacionadas ao contrato de crédito	Reenviar Documentos
Reapresentação de conta bancária	Atualizar dados bancários para desembolso após erro na transferência	Reapresentação de Conta Bancária
Cancelar dívida	Cancelar a operação antes do desembolso	Cancelamento de Dívida
Cancelar permanentemente	Cancelar permanentemente a operação de crédito	Cancelar Permanentemente

Simulação da dívida​

Request​

Response​

Objeto Installments​

Objeto Prefixed Interest Rate​

Objeto Contract Fees​

Tipos de fee (fee_type)​

Emissão da operação​

Envio de Documentos​

Request​

Rebate​

Exemplos de payload de desembolso​

Campos do borrower (Pessoa Física)​

Campos do collateral_data​

Objeto vehicle​

Objeto seller​

Response​

Enumeradores​

collateral_type​

vehicle_type​

chassi_type​

Atualização de Dados do Colateral Veicular​

Outras ações disponíveis​

Simulação da dívida

Request

Response

Objeto Installments

Objeto Prefixed Interest Rate

Objeto Contract Fees

Tipos de fee (fee_type)

Emissão da operação

Envio de Documentos

Request

Rebate

Exemplos de payload de desembolso

Campos do borrower (Pessoa Física)

Campos do collateral_data

Objeto vehicle

Objeto seller

Response

Enumeradores

collateral_type

vehicle_type

chassi_type

Atualização de Dados do Colateral Veicular

Outras ações disponíveis