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_delay": 30,
        "start_disbursement_date": "2025-05-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "installment_face_value": 500,
        "disbursed_amount": 5000.00,
        "limit_days_to_disburse": 3,
        "number_of_installments": 12
    },
    "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",
    "document_template_key": "<template-key-da-ccb-auto>",
    "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
        }
    ],
    "additional_data": {
        "vehicle_color": "Prata",
        "vehicle_condition": "used",
        "guarantors": [
            {
                "name": "Maria da Silva",
                "document_number": "12345678901",
                "email": "maria.guarantor@email.com",
                "birth_date": "1980-05-15"
            },
            {
                "name": "João Pereira",
                "document_number": "98765432100",
                "email": "joao.guarantor@email.com",
                "birth_date": "1975-11-02"
            }
        ],
        "proposal": {
            "vehicle_amount": 50000.00,
            "down_payment_amount": 5000.00,
            "associated_services_amount": 2000.00,
            "documentation_amount": 570.00
        },
        "accessories": [
            { "description": "Insulfilm", "amount": 800.00 },
            { "description": "Som automotivo", "amount": 1200.00 }
        ],
        "documentation": [
            { "description": "Transferência DETRAN", "amount": 350.00 },
            { "description": "Emplacamento", "amount": 220.00 }
        ]
    }
}

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.

Valor de desembolso (disbursed_amount)

O POST /debt aceita installment_face_value (valor da parcela), disbursed_amount (valor desembolsado) ou ambos no objeto financial. Use o(s) campo(s) que correspondem à entrada que você quer fixar — para mais detalhes do comportamento ver a seção de Simulação.

Vencimento da primeira parcela

O exemplo usa first_due_date_delay (em dias corridos a partir da data de desembolso) — alternativa ao first_due_date (data explícita). Use um ou outro.

Seguro (`vehicle_credit_insurance`)

O produto Crédito Veículo suporta a contratação de seguro prestamista junto à emissão da dívida. O seguro é informado dentro de financial.rebates e o prêmio (2,75% sobre o valor de emissão) é calculado automaticamente pela QI Tech — o parceiro apenas sinaliza a contratação com o fee_type e a description corretos.

financial.rebates — seguro Auto
{
    "rebates": [
        {
            "fee_type": "insurance_premium_qi_gross_up",
            "description": "vehicle_credit_insurance"
        }
    ]
}

Campo	Valor	Descrição
`fee_type`	`"insurance_premium_qi_gross_up"`	Indica que o prêmio do seguro deve ser embutido (gross-up) no valor da operação pela QI Tech.
`description`	`"vehicle_credit_insurance"`	Identifica o produto de seguro do Crédito Veículo.

Cálculo do prêmio

A alíquota de 2,75% sobre o valor de emissão é aplicada pela QI Tech no momento da emissão. Não é necessário enviar amount nem amount_type para este fee_type — basta sinalizar a contrataçã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), `"insurance_premium"` (prêmio de seguro) ou `"insurance_premium_qi_gross_up"` (prêmio do seguro Auto embutido pela QI Tech — ver 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"
            }
        }
    ]
}

Template da CCB Auto (`document_template_key`)

A CCB do produto Crédito Veículo possui template próprio, com Quadros específicos para dados do veículo, fornecedor, avalista e composição comercial da operação. Para emitir a CCB com esse layout, informe o document_template_key da template Auto no root do payload de POST /debt.

Campo	Tipo	Descrição	Obrig.
`document_template_key`	String	UUID da template HTML da CCB Auto cadastrada no doc-api. A QI Tech fornece a chave durante o onboarding.	SIM

Como obter a template_key

A document_template_key da CCB Auto é gerada via cadastro da template HTML no doc-api da QI Tech. A QI Tech disponibiliza a chave correspondente ao seu produto durante o onboarding em sandbox e produção. Caso precise customizar o layout (logo, dados do correspondente, textos), entre em contato com seu ponto focal.

Campos `additional_data` (metadados da CCB)

O objeto additional_data no root do payload de POST /debt (ou POST /signed_debt) agrupa metadados que aparecem apenas na CCB — são exibidos no Quadro III (Avalista), Quadro VI (Dados da Proposta), Quadro IV (Cor/Condição do Veículo) e na seção de detalhamento de acessórios/documentação.

Os valores em additional_data são display-only

Nenhum campo de additional_data afeta o cálculo financeiro da operação (IOF, Valor Liberado, parcelas, CET). A concessionária continua recebendo exatamente o valor configurado em disbursement_bank_accounts, com o IOF e demais encargos calculados a partir do financial. O additional_data apenas alimenta o template da CCB para exibição.

Campo	Tipo	Descrição	Obrig.
`additional_data.vehicle_color`	String	Cor do veículo (ex: "Prata", "Preto", "Vermelho"). Exibida no Quadro IV item 5 da CCB.	NÃO
`additional_data.vehicle_condition`	String	Condição do veículo: `"new"` (Novo) ou `"used"` (Usado). Exibida no Quadro IV item 11 (checkbox marcado conforme valor).	NÃO
`additional_data.guarantors`	Array	Lista de avalistas (cada um responde solidária e ilimitadamente pelo cumprimento das obrigações). Exibida no Quadro III-A + Cláusula 4 da CCB. Aceita 0 ou N avalistas.	NÃO
`additional_data.guarantor`	Object	(Deprecado, retrocompatibilidade) Dados de um único avalista. Use `guarantors` (array) preferencialmente — o template converte automaticamente este objeto em uma lista de tamanho 1.	NÃO
`additional_data.proposal`	Object	Dados comerciais da proposta de financiamento (Valor do Veículo, Entrada, Serviços, Documentação). Exibidos no Quadro VI da CCB.	NÃO
`additional_data.accessories`	Array	Lista de acessórios do veículo (insulfilm, som, blindagem etc.) — exibidos na seção "Detalhamento de acessórios" do Quadro VI.	NÃO
`additional_data.documentation`	Array	Lista de custos de documentação (transferência DETRAN, emplacamento etc.) — exibidos na seção "Detalhamento de documentação" do Quadro VI.	NÃO

Array `guarantors` (recomendado)

Caso o financiamento tenha um ou mais avalistas, informe-os neste array. Cada avalista aparece em uma linha do Quadro III-A – AVALISTAS da CCB, e todos respondem solidária e ilimitadamente pelas obrigações descritas na Cláusula 4 das Condições Gerais.

Campo	Tipo	Descrição	Obrig.
`additional_data.guarantors[].name`	String	Nome completo do avalista	SIM (se enviar item)
`additional_data.guarantors[].document_number`	String	CPF do avalista (11 dígitos, somente números)	SIM (se enviar item)
`additional_data.guarantors[].email`	String	E-mail do avalista	NÃO
`additional_data.guarantors[].birth_date`	String	Data de nascimento (YYYY-MM-DD)	NÃO

{
    "guarantors": [
        {
            "name": "Maria da Silva",
            "document_number": "12345678901",
            "email": "maria.guarantor@email.com",
            "birth_date": "1980-05-15"
        },
        {
            "name": "João Pereira",
            "document_number": "98765432100"
        }
    ]
}

Compatibilidade — guarantor (objeto único)

Para retrocompatibilidade, o template aceita também additional_data.guarantor (objeto único, sem array). Internamente é convertido para uma lista de tamanho 1 e renderizado no Quadro III-A da mesma forma. Recomendamos migrar para guarantors (array).

Objeto `proposal`

Os valores comerciais da proposta de financiamento aparecem no Quadro VI – Dados da Proposta da CCB. Os campos são numéricos (Float, em BRL, com até duas casas decimais) — o template faz a formatação para exibição (ex.: 50000.00 → "R$ 50.000,00").

Campo	Tipo	Descrição	Obrig.
`additional_data.proposal.vehicle_amount`	Number (float)	Valor do Veículo em BRL (Quadro VI item 1)	NÃO
`additional_data.proposal.down_payment_amount`	Number (float)	Valor da Entrada paga pelo tomador em BRL (Quadro VI item 2)	NÃO
`additional_data.proposal.associated_services_amount`	Number (float)	Totalizador de Produtos/Serviços Associados em BRL (Quadro VI item 4) — deve ser igual à soma de `accessories[].amount`	NÃO
`additional_data.proposal.documentation_amount`	Number (float)	Totalizador de Documentação em BRL (Quadro VI item 5) — deve ser igual à soma de `documentation[].amount`	NÃO

Consistência dos totalizadores

associated_services_amount precisa bater com sum(accessories[].amount) e documentation_amount precisa bater com sum(documentation[].amount). A QI Tech não recalcula esses totalizadores a partir dos arrays — quem envia é o parceiro, e divergência aparece como inconsistência no Quadro VI da CCB.

Valor Financiado é derivado automaticamente

O Valor Financiado (Quadro VI item 3) e o CET Mensal/Anual (Quadro VI itens 6 e 7) são derivados automaticamente do issue_amount e dos dados financeiros da operação — não precisam ser enviados em additional_data.proposal.

Arrays `accessories` e `documentation`

Listas de itens que serão exibidos na CCB na seção "Detalhamento de acessórios e documentação" do Quadro VI, agrupados por categoria. O total de cada categoria também é exibido no campo correspondente da Tabela de Despesas Acessórias (itens 16 e 17).

Campo	Tipo	Descrição	Obrig.
`additional_data.accessories[].description`	String	Descrição livre do item, exibida na CCB (até 255 caracteres)	SIM (se enviar item)
`additional_data.accessories[].amount`	Number	Valor do item em BRL (mínimo 0)	SIM (se enviar item)
`additional_data.documentation[].description`	String	Descrição livre do item, exibida na CCB (até 255 caracteres)	SIM (se enviar item)
`additional_data.documentation[].amount`	Number	Valor do item em BRL (mínimo 0)	SIM (se enviar item)

Exemplo completo

{
    "additional_data": {
        "vehicle_color": "Prata",
        "vehicle_condition": "used",
        "guarantors": [
            {
                "name": "Maria da Silva",
                "document_number": "12345678901",
                "email": "maria.guarantor@email.com",
                "birth_date": "1980-05-15"
            },
            {
                "name": "João Pereira",
                "document_number": "98765432100",
                "email": "joao.guarantor@email.com",
                "birth_date": "1975-11-02"
            }
        ],
        "proposal": {
            "vehicle_amount": 50000.00,
            "down_payment_amount": 5000.00,
            "associated_services_amount": 2000.00,
            "documentation_amount": 570.00
        },
        "accessories": [
            { "description": "Insulfilm", "amount": 800.00 },
            { "description": "Som automotivo", "amount": 1200.00 }
        ],
        "documentation": [
            { "description": "Transferência DETRAN", "amount": 350.00 },
            { "description": "Emplacamento", "amount": 220.00 }
        ]
    }
}

Mapeamento additional_data → Quadros da CCB

Campo `additional_data`	Onde aparece na CCB
`vehicle_color`	Quadro IV item 5 (Cor)
`vehicle_condition`	Quadro IV item 11 (Condição: Novo/Usado)
`guarantors[].name` / `guarantors[].document_number` / `guarantors[].email`	Quadro III-A (uma linha por avalista) + Cláusula 4
`proposal.vehicle_amount`	Quadro VI item 1 (Valor do Veículo)
`proposal.down_payment_amount`	Quadro VI item 2 (Valor da Entrada)
`proposal.associated_services_amount`	Quadro VI item 4 (Produtos/Serviços Associados)
`proposal.documentation_amount`	Quadro VI item 5 (Documentação)
`accessories[]`	Quadro VI seção "Detalhamento de acessórios" + Tabela Despesas Acessórias item 16
`documentation[]`	Quadro VI seção "Detalhamento de documentação" + Tabela Despesas Acessórias item 17

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

Campos do additional_data

Metadados exibidos exclusivamente na CCB Auto. Nenhum desses campos altera IOF, Valor Liberado, parcelas ou CET da operação — são display-only no template da CCB.

Campo	Tipo	Descrição	Obrig.
vehicle_color	String	Cor do veículo (ex: "Prata", "Preto"). Quadro IV item 5 da CCB.	NÃO
vehicle_condition	String	Condição do veículo: `new` (Novo) ou `used` (Usado). Quadro IV item 11 da CCB.	NÃO
guarantors	Array	Lista de avalistas (cada um responde solidariamente). Quadro III-A + Cláusula 4 da CCB.	NÃO
guarantor	Object	(Deprecado, retrocompat) Avalista único. Use `guarantors`.	NÃO
proposal	Object	Dados comerciais da proposta (Valor do Veículo, Entrada, Serviços, Documentação). Quadro VI da CCB.	NÃO
accessories	Array	Lista de acessórios do veículo (insulfilm, som etc.). Quadro VI seção "Detalhamento de acessórios" + Tabela Despesas Acessórias item 16.	NÃO
documentation	Array	Lista de custos de documentação (transferência DETRAN, emplacamento etc.). Quadro VI seção "Detalhamento de documentação" + Tabela Despesas Acessórias item 17.	NÃO

Array guarantors

Cada item da lista representa um avalista, exibido como uma linha do Quadro III-A da CCB.

Campo	Tipo	Descrição	Obrig.
name	String	Nome completo do avalista	SIM (se enviar item)
document_number	String	CPF do avalista (11 dígitos, somente números)	SIM (se enviar item)
email	String	E-mail do avalista	NÃO
birth_date	String	Data de nascimento (YYYY-MM-DD)	NÃO

A chave guarantor (objeto único) ainda é aceita por retrocompatibilidade e tratada como uma lista de tamanho 1.

Objeto proposal

Campo	Tipo	Descrição	Obrig.
vehicle_amount	Number (float)	Valor do Veículo em BRL (Quadro VI item 1)	NÃO
down_payment_amount	Number (float)	Valor da Entrada paga pelo tomador em BRL (Quadro VI item 2)	NÃO
associated_services_amount	Number (float)	Totalizador de Produtos/Serviços Associados em BRL (Quadro VI item 4) — deve ser igual à soma de `accessories[].amount`	NÃO
documentation_amount	Number (float)	Totalizador de Documentação em BRL (Quadro VI item 5) — deve ser igual à soma de `documentation[].amount`	NÃO

Array accessories

Campo	Tipo	Descrição	Obrig.
description	String	Descrição livre do item, exibida na CCB (até 255 caracteres)	SIM (se enviar item)
amount	Number	Valor do item em BRL (mínimo 0)	SIM (se enviar item)

Array documentation

Campo	Tipo	Descrição	Obrig.
description	String	Descrição livre do item, exibida na CCB (até 255 caracteres)	SIM (se enviar item)
amount	Number	Valor do item em BRL (mínimo 0)	SIM (se enviar item)

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

Cancelamento

Os fluxos de cancelamento da operação (antes do desembolso, devolução via /debt/reversal ou cancelamento permanente) estão documentados na página dedicada: Cancelamento.

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
Devolução pela concessionária	Gerar Pix QR Code para a concessionária devolver o valor desembolsado e liberar a alienação	`/debt/reversal`

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​

Seguro (vehicle_credit_insurance)​

Rebate​

Template da CCB Auto (document_template_key)​

Campos additional_data (metadados da CCB)​

Array guarantors (recomendado)​

Objeto proposal​

Arrays accessories e documentation​

Exemplo completo​

Exemplos de payload de desembolso​

Campos do borrower (Pessoa Física)​

Campos do collateral_data​

Objeto vehicle​

Objeto seller​

Campos do additional_data​

Array guarantors​

Objeto proposal​

Array accessories​

Array documentation​

Response​

Enumeradores​

collateral_type​

vehicle_type​

chassi_type​

Atualização de Dados do Colateral Veicular​

Cancelamento​

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

Seguro (`vehicle_credit_insurance`)

Rebate

Template da CCB Auto (`document_template_key`)

Campos `additional_data` (metadados da CCB)

Array `guarantors` (recomendado)

Objeto `proposal`

Arrays `accessories` e `documentation`

Exemplo completo

Exemplos de payload de desembolso

Campos do borrower (Pessoa Física)

Campos do collateral_data

Objeto vehicle

Objeto seller

Campos do additional_data

Array guarantors

Objeto proposal

Array accessories

Array documentation

Response

Enumeradores

collateral_type

vehicle_type

chassi_type

Atualização de Dados do Colateral Veicular

Cancelamento

Outras ações disponíveis