# QI Tech — Garantias › Garantia Veicular

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
8 página(s).

Índice:
- Aprovação de Reserva (/documentation/garantia_veicular/aprovacao_reserva)
- Cancelamento (/documentation/garantia_veicular/cancelamento)
- Consultas (/documentation/garantia_veicular/consultas)
- Mapa de Status e Etapas (/documentation/garantia_veicular/mapa_de_status)
- Simulação e Emissão (/documentation/garantia_veicular/simulacao_e_emissao)
- Mocks (Sandbox) (/documentation/garantia_veicular/testes_homologacao)
- Webhooks — Garantia Veicular (/documentation/garantia_veicular/webhooks)
- Manual de Garantia Veicular (/documentation/manual_garantia_veicular/)

---

# Aprovação de Reserva

URL: /documentation/garantia_veicular/aprovacao_reserva

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

Quando a configuração do requester define que reservas precisam de aprovação manual (`allow_reservation: false`), toda nova reserva é criada com `is_allowed_to_reserve = false`. Nesse estado, a reserva permanece em `pending_reservation` e **não é processada** pela rotina automática — fica aguardando uma aprovação explícita.

Este endpoint libera a reserva manualmente, alterando `is_allowed_to_reserve` para `true`. A partir daí, o próximo ciclo da rotina automática avança a reserva para `pending_reservation_confirmation` (veja [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)).

:::info O `status` da reserva não muda com a chamada
O `reservation_status` continua `pending_reservation` antes e depois do approve. O que muda é o flag `is_allowed_to_reserve`, que destrava o processamento automático. O avanço para `pending_reservation_confirmation` acontece na próxima execução da rotina.
:::

## Aprovar Reserva

ENDPOINT /debt/ OPERATION-KEY /vehicle_collateral/reservation/approve
MÉTODO POST

O `OPERATION-KEY` é o `operation_key` da operação de crédito. A requisição **não exige body**.

Response Body (200)

```json
{
    "reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "external_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "reservation_status": "pending_reservation",
    "is_allowed_to_reserve": true,
    "document_number": "12345678901",
    "inclusion_date": "2026-06-15"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| reservation_key | String (UUID) | Identificador interno da reserva |
| external_key | String (UUID) | Identificador da operação (mesmo enviado na URL) |
| reservation_status | String | Status atual da reserva. Permanece `pending_reservation` após o approve (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| is_allowed_to_reserve | Boolean | `true` após a aprovação — libera o processamento automático |
| document_number | String | CPF/CNPJ do tomador |
| inclusion_date | String (`YYYY-MM-DD`) | Data de criação da reserva |

:::tip Idempotência
Chamar o endpoint quando `is_allowed_to_reserve` já é `true` retorna 200 normalmente, sem alterar o estado. Pode ser usado com segurança em retries.
:::

:::caution Validação de propriedade
A reserva precisa pertencer ao requester autenticado. Caso contrário, a resposta é `404 Not Found`.
:::

---

# Cancelamento

URL: /documentation/garantia_veicular/cancelamento

O cancelamento de uma operação de Crédito Veículo pode ocorrer em três cenários distintos, cada um com um endpoint próprio. Em todos os casos, **a alienação fiduciária / gravame é removida automaticamente do veículo** após a confirmação do cancelamento.

| Cenário | Quando usar | Endpoint |
|---------|-------------|----------|
| Antes do desembolso | Operação criada mas ainda não desembolsada para a concessionária | `PATCH /debt/{DEBT-KEY}/cancel` |
| Devolução pela concessionária | Operação já desembolsada — a concessionária devolve o valor via Pix QR Code | `POST /debt/reversal` |
| Cancelamento permanente | Desistência definitiva da operação (encerramento sem possibilidade de reativação) | `POST /debt/{DEBT-KEY}/cancel_permanently` |

**Antes do desembolso**

Enquanto a operação ainda não foi desembolsada, é possível cancelá-la diretamente pelo endpoint `PATCH /debt/{DEBT-KEY}/cancel`. Como não há valor a ser devolvido (nenhum recurso saiu da QI Tech para a concessionária), o cancelamento é imediato.

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

A referência completa do endpoint, incluindo o response body, está em [Cancelar dívida antes de desembolsar](/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar).

:::info Quando usar
Use este endpoint sempre que a operação ainda **não tenha sido desembolsada** (status anterior ao desembolso à concessionária). Após o desembolso, utilize o fluxo de devolução via `/debt/reversal`.
:::

**Devolução via /debt/reversal**

Após o desembolso, o cancelamento se dá pela devolução do valor à QI Tech via Pix QR Code. **No Crédito Veículo, quem paga o QR Code é a concessionária** (que recebeu o desembolso original), e não o tomador. Confirmado o pagamento, a operação é cancelada e a alienação/gravame é removida do veículo no SNG/Detran. Se a cessão já tiver ocorrido, o valor é estornado para o cessionário.

**Passo a passo**

1. O parceiro chama o endpoint **`POST /debt/reversal`** informando o `contract_number` da operação a ser cancelada.
2. A QI Tech responde com um Pix QR Code de devolução (`copy_paste_pix`, `amount`, `expiration_date`).
3. O parceiro **repassa o QR Code à concessionária** (que recebeu o desembolso original).
4. A concessionária paga o QR Code.
5. Uma vez confirmado o pagamento, a operação é cancelada automaticamente e a **alienação fiduciária / gravame é removida** do veículo no SNG/Detran. Se a cessão já tiver ocorrido, o valor é estornado para o cessionário.

**Request**

```json title='POST /debt/reversal'
{
    "contract_number": "0000049343/TW"
}
```

Campos opcionais: `days_to_expire` (dias corridos) ou `workdays_to_expire` (dias úteis) para customizar a expiração do QR Code (padrão: 14 dias úteis).

**Response**

```json
{
    "amount": "10641.24",
    "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-...",
    "expiration_date": "2025-05-24",
    "payer_document_number": "98765432000100",
    "payer_name": "CONCESSIONARIA EXEMPLO VEICULOS",
    "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
    "status": "waiting_payment"
}
```

:::info Referências completas
- [Geração do Pix QR Code de devolução (`POST /debt/reversal`)](/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) — referência completa do endpoint, incluindo campos e respostas de erro.
- [Consulta do Pix QR Code de devolução](/documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao) — para acompanhar o status do pagamento.
:::

:::tip Pré-requisito
Para utilizar o endpoint é necessário solicitar à QI Tech a liberação e a configuração da conta de estorno do cessionário.
:::

**Cancelamento permanente**

O cancelamento permanente encerra a operação de crédito de forma definitiva, **sem possibilidade de reativação**. Use este endpoint quando a desistência for definitiva e nenhum dos fluxos de retomada (reapresentação de conta, reenvio de documentos, etc.) for aplicável.

ENDPOINT /debt/ debt_key /cancel_permanently
MÉTODO POST

A referência completa do endpoint, incluindo o response body, está em [Cancelar permanentemente](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente).

:::danger Operação irreversível
Após o `cancel_permanently`, a operação **não pode ser reativada**. Avalie se as alternativas (`/cancel` antes do desembolso, ou `/debt/reversal` após) atendem ao seu caso de uso antes de utilizar este endpoint.
:::

---

# Consultas

URL: /documentation/garantia_veicular/consultas

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Consultar Dívida

Retorna os dados de uma dívida ou uma lista paginada de dívidas. Os filtros são passados como query parameters.

ENDPOINT /debt
MÉTODO GET

### Query Parameters

| Parâmetro | Tipo | Descrição | Obrig. |
|-----------|------|-----------|--------|
| key | String (UUID) | Identificador único da dívida | NÃO |
| contract_number | String | Número do contrato | NÃO |
| issuer_document_number | String | CPF ou CNPJ do tomador | NÃO |
| status | String | Status da dívida (ex: `opened`, `waiting_signature`, `disbursed`, `canceled`, `settled`) | NÃO |
| page | Integer | Número da página (padrão: 1) | NÃO |
| page_size | Integer | Quantidade de registros por página (padrão: 10, máx: 100) | NÃO |

### Response — Busca por key (registro único)

STATUS 200

Response Body

```json
{
    "data": {
        "key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "contract_number": "OP-000000000000001",
        "status": "disbursed",
        "borrower": {
            "name": "João da Silva",
            "document_number": "12345678901",
            "person_type": "natural"
        },
        "financial": {
            "interest_type": "pre_price_days",
            "credit_operation_type": "ccb",
            "monthly_interest_rate": 0.018,
            "number_of_installments": 12,
            "issue_amount": 5419.55,
            "disbursement_date": "2025-05-10",
            "first_due_date": "2025-06-15"
        },
        "collaterals": [
            {
                "collateral_type": "vehicle",
                "collateral_key": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
                "collateral_data": {
                    "vehicle_type": "automobile",
                    "plate": "ABC1D23",
                    "license_state": "SP",
                    "chassi_number": "9BWZZZ37780001234",
                    "renavam": "12345678901"
                }
            }
        ],
        "created_at": "2025-05-10T14:30:00.000000",
        "updated_at": "2025-05-10T16:00:00.000000"
    }
}
```

### Response — Busca paginada (lista)

Response Body

```json
{
    "data": [
        {
            "key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "contract_number": "OP-000000000000001",
            "status": "disbursed",
            "borrower": {
                "name": "João da Silva",
                "document_number": "12345678901",
                "person_type": "natural"
            },
            "financial": {
                "issue_amount": 5419.55,
                "number_of_installments": 12,
                "disbursement_date": "2025-05-10"
            },
            "created_at": "2025-05-10T14:30:00.000000"
        }
    ],
    "pagination": {
        "current_page": 1,
        "page_size": 10,
        "total_pages": 1,
        "total_items": 1
    }
}
```

---

## Consultar Reserva (Gravame)

Retorna o status atual do registro de gravame no SNG/B3.

ENDPOINT /debt/ DEBT-KEY /vehicle_collateral/reservation
MÉTODO GET

Response Body (200)

```json
{
    "status": "reserved",
    "last_updated_at": "2026-02-13 20:38:07",
    "chassi_number": "9BWZZZ37780001234",
    "license_state": "SP",
    "collateral_number": "12345678"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | String | Status atual do gravame (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)). Valores possíveis: `pending_reservation`, `pending_reservation_confirmation`, `reserved`, `pending_requester_action`, `refused` |
| last_updated_at | String | Timestamp da última atualização (`YYYY-MM-DD HH:MM:SS`) |
| chassi_number | String | Número do chassi do veículo |
| license_state | String | UF de licenciamento do veículo (2 chars, caixa alta) |
| collateral_number | String | Número da garantia (até 8 chars; `"0"` se ainda não disponível) |

---

## Consultar Contrato (Registro DETRAN)

Retorna o status atual do registro de contrato no DETRAN/Registradora.

ENDPOINT /debt/ DEBT-KEY /vehicle_collateral/contract
MÉTODO GET

Response Body (200)

```json
{
    "status": "pending_registration_confirmation",
    "last_updated_at": "2026-02-14 10:45:07",
    "chassi_number": "9BWZZZ37780001234",
    "license_state": "SP"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | String | Status atual do contrato (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)). Valores possíveis: `pending_registration_confirmation`, `pending_send_contract`, `pending_send_contract_confirmation`, `deleted` |
| last_updated_at | String | Timestamp da última atualização (`YYYY-MM-DD HH:MM:SS`) |
| chassi_number | String | Número do chassi do veículo |
| license_state | String | UF de licenciamento do veículo (2 chars, caixa alta) |

---

## Endpoints Auxiliares

| Endpoint | Método | Descrição |
|----------|--------|-----------|
| `/` | GET | Nome do serviço e PID |
| `/health_check` | GET | `204 No Content` — health check |
| `/vehicle_collateral/fees?state=&vehicle_type=` | GET | Cálculo de tarifas por estado e tipo de veículo |
| `/vehicle_collateral/mock_time` | GET | Datetime atual — disponível apenas em DEV/LOCAL/SANDBOX |

---

# Mapa de Status e Etapas

URL: /documentation/garantia_veicular/mapa_de_status

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Visão Geral — Ciclo de Vida Completo

O diagrama abaixo apresenta o ciclo de vida completo de uma operação com garantia veicular, desde a criação da dívida até a conclusão do registro de contrato e imagem.

![Ciclo de vida completo de uma operação com garantia veicular](/img/diagrams/garantia-veicular-mapa-de-status-1.svg)

---

## Ciclo de Vida do Colateral (Gravame)

Após a assinatura do contrato, a QI Tech envia automaticamente a solicitação de inclusão de gravame ao SNG/B3.

![Ciclo de vida do colateral (gravame)](/img/diagrams/garantia-veicular-mapa-de-status-2.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Reserva Pendente | `pending_reservation` | Dados inseridos na plataforma, aguardando envio ao SNG/B3 |
| Confirmação de Reserva Pendente | `pending_reservation_confirmation` | Dados enviados ao SNG/B3. Aguardando confirmação do registro de gravame |
| Reservado | `reserved` | Gravame registrado com sucesso no SNG/B3. Operação pronta para desembolso e registro de contrato |
| Ação do Requester Pendente | `pending_requester_action` | Erro nos dados enviados ou restrição detectada. Parceiro deve corrigir e reenviar |
| Cancelado | `canceled` | Solicitação cancelada na plataforma |

### Ciclo de Cancelamento (Exclusão do Gravame)

Quando uma operação precisa ser cancelada após o gravame ter sido registrado, o fluxo de exclusão é acionado:

![Ciclo de cancelamento e exclusão do gravame](/img/diagrams/garantia-veicular-mapa-de-status-3.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Exclusão Pendente | `pending_deletion` | Cancelamento solicitado, aguardando envio da exclusão ao SNG/B3 |
| Confirmação de Exclusão Pendente | `pending_deletion_confirmation` | Solicitação de exclusão enviada. Aguardando confirmação do SNG/B3 |
| Excluído | `deleted` | Colateral e contrato totalmente cancelados no SNG/B3 e DETRAN |

---

## Ciclo de Vida do Contrato

Após o gravame ser confirmado (`reserved`) e o desembolso realizado, a QI Tech envia automaticamente o registro de contrato ao DETRAN/Registradora.

![Ciclo de vida do contrato](/img/diagrams/garantia-veicular-mapa-de-status-4.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Confirmação de Registro Pendente | `pending_registration_confirmation` | Contrato enviado ao DETRAN/Registradora. Aguardando validação e registro |
| Registrado | `registered` | Contrato registrado com sucesso no DETRAN. Próximo passo: envio de imagem |
| Envio de Contrato Pendente | `pending_send_contract` | Contrato registrado, aguardando envio de imagem do contrato |
| Confirmação de Envio de Contrato Pendente | `pending_send_contract_confirmation` | Imagem enviada ao DETRAN/Registradora. Aguardando validação |
| Ação do Requester Pendente | `pending_requester_action` | Balcão DETRAN (DF/TO: devedor deve comparecer fisicamente) ou dados/imagem inválidos |
| Excluído | `deleted` | Contrato cancelado na plataforma |

:::info Status Internos
Os status de validação de imagem (ex: `invalid_image`) são exclusivamente internos e **não** são enviados aos clientes externos via webhook.
:::

---

# Simulação e Emissão

URL: /documentation/garantia_veicular/simulacao_e_emissao

:::caution 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**

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

**Valor de parcela com valor de desembolso**

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

:::info
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

```json
{
    "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. |

:::info 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](/documentation/upload_de_documentos/upload_de_documentos)).

:::danger 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 |

:::info Upload de Documentos
Consulte a documentação completa de upload: [Upload de Documentos](/documentation/upload_de_documentos/upload_de_documentos). Não é necessário enviar documentos do veículo.
:::

### Request

ENDPOINT /debt
MÉTODO POST

Testar no Playground

Request Body

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

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

:::tip 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.
:::

:::info 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](#simulação-da-dívida).
:::

:::info 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.

```json title='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. |

:::info 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](#seguro-vehicle_credit_insurance)) |
| `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 |

```json
{
    "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 |

:::info 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.

:::danger 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 |

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

:::info 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 |

:::warning 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.
:::

:::info 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

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

:::info 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)**

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

**Pix (manual)**

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

**TED**

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

**QR Code Pix**

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

**Boleto**

```json
{
    "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](#vehicle_type)) | 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

```json
{
    "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": "3571e292-3a83-4011-904d-20ee963022ef"
        },
        "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

:::caution 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

```json
{
    "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](/documentation/garantia_veicular/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](/documentation/emissao_de_divida/autorizar_desembolso) |
| Atualizar dados da parte relacionada | Atualizar informações cadastrais (endereço, telefone, e-mail) das partes relacionadas ao contrato | [Atualizar Parte Relacionada](/documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada) |
| Reenviar documentos | Reenviar documentos das partes relacionadas ao contrato de crédito | [Reenviar Documentos](/documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas) |
| Reapresentação de conta bancária | Atualizar dados bancários para desembolso após erro na transferência | [Reapresentação de Conta Bancária](/documentation/emissao_de_divida/reapresentacao_de_conta_bancaria) |
| Cancelar dívida | Cancelar a operação antes do desembolso | [Cancelamento de Dívida](/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar) |
| Cancelar permanentemente | Cancelar permanentemente a operação de crédito | [Cancelar Permanentemente](/documentation/emissao_de_divida/cancelamento/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`](/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) |

---

# Mocks (Sandbox)

URL: /documentation/garantia_veicular/testes_homologacao

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

O ambiente de homologação (sandbox) possui um sistema de mocks que simula diferentes cenários de resposta do SNG/B3 durante o registro de gravame. O comportamento é controlado pelo campo `name` do tomador (borrower) na criação da dívida (`POST /debt`).

:::tip Fluxo Padrão (Sucesso)
Qualquer `name` que **não esteja** na lista de cenários abaixo seguirá o fluxo padrão de sucesso: o gravame será registrado (`reserved`), seguido pela criação automática do contrato (`pending_registration_confirmation`) e prosseguimento até o desembolso. Dois webhooks são enviados em sequência: `reservation.status_change` (status `reserved`) e `contract.status_change` (status `pending_registration_confirmation`). Para detalhes sobre a estrutura dos webhooks, consulte a página de [Webhooks](/documentation/garantia_veicular/webhooks).
:::

---

## Cenários Disponíveis

### Erro de Validação de Campos (HTTP 400)

Ao utilizar o nome `bob`, a criação do gravame é rejeitada com erros de validação de campos no payload.

| Nome | Etapa | Status Resultante | Webhook |
| :---: | --- | :---: | :---: |
| `bob` | Criação do gravame | `pending_requester_action` | Sim |

**Exemplo de webhook completo**

```json
{
  "event_key": "a23bc45d-67ef-8901-abcd-234567890abc",
  "event_type": "laas.vehicle_collateral.reservation.status_change",
  "origin": "vehicle_collateral",
  "origin_key": "<reservation_key>",
  "person_key": "<requester_key>",
  "receiver_contact": null,
  "data": {
    "callback": {
      "webhook_type": "laas.vehicle_collateral.reservation.status_change",
      "status": "pending_requester_action",
      "event_datetime": "2026-04-08T15:30:00.000Z",
      "data": {
        "contract_number": "CTR-2026-001",
        "rejection_details": [
          {
            "campo": "logradouroDevedor",
            "mensagem": "caracter inválido / acima do tamanho permitido / tipo inválido / Ausência do campo"
          },
          {
            "campo": "numTelDevedor",
            "mensagem": "caracter inválido / acima do tamanho permitido"
          }
        ]
      }
    }
  }
}
```

---

### Erros de Negócio na Confirmação do Gravame

Os cenários abaixo são acionados na etapa de confirmação de status. Todos resultam em `pending_requester_action` e enviam webhook com `error_code`.

| Nome | Erro | `error_code` |
| :---: | --- | --- |
| `carol` | Veículo com restrição financeira já cadastrada | `vehicle_has_financial_restriction_already_registered` |
| `dave` | Chassi não localizado na BIN | `chassis_not_found_in_bin` |
| `frank` | Placa na BIN, informe a placa do veículo | `plate_in_bin_inform_plate_of_vehicle` |
| `george` | Placa divergente da base BIN | `plate_informed_different_from_plate_informed_by_uf_of_registration_in_bin_base` |
| `ian` | Número do imóvel não corresponde ao CEP | `property_number_does_not_correspond_to_informed_postal_code` |
| `jack` | RENAVAM divergente | `renavam_informed_different_from_renavam_informed_by_uf_of_registration_in_bin_base` |
| `kate` | UF do imóvel inválida | `property_uf_invalid` |
| `mary` | Endereço com preenchimento inválido | `financied_address_with_invalid_fill` |
| `olive` | Ano modelo divergente da BIN | `model_year_informed_different_from_model_year_in_bin` |
| `quinn` | Protocolo em aberto na UF de licenciamento | `protocol_open_in_uf_of_registration` |
| `sara` | Nome e endereço do financiado inválidos | `financied_name_and_address_with_invalid_fill` |
| `taylor` | Nome do financiado inválido | `financied_name_with_invalid_fill` |
| `vincent` | Veículo já alienado na base estadual | `vehicle_already_reserved_in_state_base` |

**Exemplo de webhook completo (cenário carol )**

```json
{
  "event_key": "<uuid>",
  "event_type": "laas.vehicle_collateral.reservation.status_change",
  "origin": "vehicle_collateral",
  "origin_key": "<reservation_key>",
  "person_key": "<requester_key>",
  "receiver_contact": null,
  "data": {
    "callback": {
      "webhook_type": "laas.vehicle_collateral.reservation.status_change",
      "key": "<reservation_key>",
      "status": "pending_requester_action",
      "event_datetime": "2026-04-08T15:30:00.000Z",
      "data": {
        "contract_number": "CTR-2026-001",
        "error_code": "vehicle_has_financial_restriction_already_registered",
        "error_reason_en": "Vehicle has financial restriction already registered",
        "error_reason_pt": "Veículo com restrição financeira já cadastrada"
      }
    }
  }
}
```

---

### Recusa Definitiva (sem webhook)

Nestes casos, a reserva é recusada definitivamente. **Nenhum webhook é enviado ao cliente.**

| Nome | Erro | Status Resultante |
| :---: | --- | :---: |
| `eve` | Restrição na BIN fabril | `refused` |
| `robert` | Veículo com restrição | `refused` |

---

### Reprocessamento Automático (sem webhook)

Nestes casos, a mensagem é devolvida para reprocessamento automático. **Nenhum webhook é enviado ao cliente.**

| Nome | Erro | Comportamento |
| :---: | --- | --- |
| `gabriel` | Erro desconhecido | Reprocessamento automático |
| `henry` | Proprietário divergente na comunicação de venda | Reprocessamento automático |
| `linda` | Restrição na UF de licenciamento | Reprocessamento automático |
| `nancy` | Nome do endereço acima de 30 caracteres | Reprocessamento automático |
| `paul` | Telefone acima de 9 caracteres | Reprocessamento automático |
| `william` | Erro desconhecido | Reprocessamento automático |

---

## Tabela Resumo

| Nome | Etapa | Status Resultante | Webhook | Tipo |
| :---: | --- | :---: | :---: | --- |
| `bob` | Criação (HTTP 400) | `pending_requester_action` | Sim | `reservation.status_change` com `rejection_details` |
| `carol` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `dave` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `eve` | Confirmação | `refused` | Não | — |
| `frank` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `george` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `gabriel` | Confirmação | Reprocessamento | Não | — |
| `henry` | Confirmação | Reprocessamento | Não | — |
| `ian` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `jack` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `kate` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `linda` | Confirmação | Reprocessamento | Não | — |
| `mary` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `nancy` | Confirmação | Reprocessamento | Não | — |
| `olive` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `paul` | Confirmação | Reprocessamento | Não | — |
| `quinn` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `robert` | Confirmação | `refused` | Não | — |
| `sara` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `taylor` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `vincent` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `william` | Confirmação | Reprocessamento | Não | — |
| *(outro)* | — | `reserved` + `pending_registration_confirmation` | Sim (2x) | `reservation.status_change` + `contract.status_change` |

:::warning Atenção
Os mocks acima simulam apenas a etapa de **registro de gravame** (reserva). O fluxo de registro de contrato e envio de imagem não possui mocks dedicados no ambiente de homologação.
:::

---

# Webhooks — Garantia Veicular

URL: /documentation/garantia_veicular/webhooks

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

Notificações assíncronas enviadas via POST pela QI Tech para reportar mudanças de status no ciclo de vida do colateral (gravame), contrato e dívida. A requisição deve ser respondida em até **5 segundos** com HTTP 200.

:::info Webhooks de Dívida
Esta seção cobre tanto os webhooks de **garantia veicular** quanto os webhooks padrão de **dívida**. Para a documentação completa de todos os webhooks relacionados a dívidas, consulte: [Webhooks de Dívida](/documentation/webhooks/dividas).
:::

---

## Webhooks de Garantia Veicular — Reserva (SNG/B3)

WEBHOOK TYPE
laas.vehicle_collateral.reservation.status_change

Notificações relacionadas ao registro de **gravame** no SNG/B3.

### Estrutura Base do Webhook

```json
{
    "key": "<UUID v4 — identificador único do webhook>",
    "reservation_key": "<UUID — identificador único da reserva>",
    "credit_operation_key": "<UUID — identificador da operação de crédito>",
    "status": "<enumerador de status>",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "<timestamp ISO 8601>",
    "data": {
        "contract_number": "<número do contrato>",
        "...": "<campos específicos do status>"
    }
}
```

#### Campos Base

| Campo | Tipo | Descrição |
|-------|------|-----------|
| key | String | Identificador único do webhook (UUID v4) |
| reservation_key | String | Identificador único da reserva (UUID) |
| credit_operation_key | String | Identificador da operação de crédito (UUID) |
| status | String | Enumerador de status (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| webhook_type | String | Sempre `laas.vehicle_collateral.reservation.status_change` |
| event_datetime | String | Timestamp do evento (ISO 8601) |
| data | Object | Payload específico do status (ver exemplos abaixo) |

---

### `pending_reservation_confirmation`

Colateral em processamento. Dados foram enviados para SNG/B3 e o sistema aguarda confirmação.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_reservation_confirmation",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:05:00Z",
    "data": {
        "contract_number": "123insd"
    }
}
```

---

### `reserved`

Colateral reservado com sucesso no SNG/B3. Gravame registrado e operação pronta para a próxima etapa.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "reserved",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:10:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "reservation_date": "2026-03-10"
    }
}
```

---

### `pending_requester_action` (Reserva)

Erro durante o processamento do gravame no SNG/B3. Dados inválidos ou restrição detectada. O parceiro deve corrigir as informações e reenviar.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_requester_action",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:12:00Z",
    "data": {
        "contract_number": "123insd",
        "error_code": "INVALID_CHASSIS",
        "error_reason": "Chassi informado não corresponde aos registros do veículo",
        "error_details": {
            "field": "chassis",
            "expected": "LISD931",
            "received": "LISD930"
        }
    }
}
```

---

### `deleted`

Colateral e contrato cancelados. A operação foi revertida no SNG/B3 e DETRAN.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "deleted",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T15:30:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "cancellation_date": "2026-03-10",
        "reason": "client_request"
    }
}
```

---

### Campos de Data por Status (Reserva)

| Status | Campos em data | Descrição |
|--------|----------------|-----------|
| `pending_reservation_confirmation` | `contract_number` | Gravame enviado ao SNG/B3, aguardando confirmação |
| `reserved` | `contract_number`, `collateral_number`, `reservation_date` | Gravame registrado com sucesso |
| `pending_requester_action` | `contract_number`, `error_code`, `error_reason`, `error_details` | Erro — parceiro deve corrigir os dados |
| `deleted` | `contract_number`, `collateral_number`, `cancellation_date`, `reason` | Operação cancelada |

:::caution Atenção
Os status relacionados a imagens são exclusivamente internos e **não** são enviados ao cliente externo via webhook.
:::

---

## Webhooks de Garantia Veicular — Registro (DETRAN)

WEBHOOK TYPE
laas.vehicle_collateral.contract.status_change

Notificações relacionadas ao **registro de contrato** no DETRAN/Registradora.

### Estrutura Base do Webhook

```json
{
    "key": "<UUID v4 — identificador único do webhook>",
    "reservation_key": "<UUID — identificador único da reserva>",
    "credit_operation_key": "<UUID — identificador da operação de crédito>",
    "status": "<enumerador de status>",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "<timestamp ISO 8601>",
    "data": {
        "contract_number": "<número do contrato>",
        "...": "<campos específicos do status>"
    }
}
```

#### Campos Base

| Campo | Tipo | Descrição |
|-------|------|-----------|
| key | String | Identificador único do webhook (UUID v4) |
| reservation_key | String | Identificador único da reserva (UUID) |
| credit_operation_key | String | Identificador da operação de crédito (UUID) |
| status | String | Enumerador de status (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| webhook_type | String | Sempre `laas.vehicle_collateral.contract.status_change` |
| event_datetime | String | Timestamp do evento (ISO 8601) |
| data | Object | Payload específico do status (ver exemplos abaixo) |

---

### `pending_registration_confirmation`

Contrato em processamento no DETRAN. Documento enviado e o sistema aguarda validação.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_registration_confirmation",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:15:00Z",
    "data": {
        "contract_number": "123insd",
        "stage": "contract_registration"
    }
}
```

---

### `registered`

Contrato registrado com sucesso no DETRAN. Ciclo completo finalizado. Colateral e contrato estão ativos e válidos.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "registered",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:20:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "registration_date": "2026-03-10",
        "completion_timestamp": "2026-03-10T10:20:00Z"
    }
}
```

---

### `pending_requester_action` (Registro)

Erro durante o processamento do contrato no DETRAN. Dados inválidos ou balcão detectado. O parceiro deve corrigir as informações e reenviar.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_requester_action",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:22:00Z",
    "data": {
        "contract_number": "123insd",
        "error_code": "INVALID_CONTRACT_DATA",
        "error_reason": "Dados do contrato inválidos ou balcão DETRAN",
        "error_details": {
            "stage": "contract_registration"
        }
    }
}
```

---

### Campos de Data por Status (Registro)

| Status | Campos em data | Descrição |
|--------|----------------|-----------|
| `pending_registration_confirmation` | `contract_number`, `stage` | Contrato enviado ao DETRAN, aguardando validação |
| `registered` | `contract_number`, `collateral_number`, `registration_date`, `completion_timestamp` | Ciclo completo finalizado |
| `pending_requester_action` | `contract_number`, `error_code`, `error_reason`, `error_details` | Erro — parceiro deve corrigir os dados |

---

## Webhooks de Dívida

WEBHOOK TYPE
debt

Os webhooks abaixo notificam sobre mudanças no ciclo de vida da **dívida** associada à garantia veicular. Estes são os mesmos webhooks padrão de dívida documentados em [Webhooks de Dívida](/documentation/webhooks/dividas).

---

### `waiting_signature`

Contrato gerado e disponível para assinatura. A URL de assinatura é enviada neste webhook.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 14:30:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/CONCESSIONARIA-CCB-OP000000000000001.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "NOME DO REPRESENTANTE",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": "representante@concessionaria.com.br",
                    "signature_url": "https://sign.qitech.com.br/<uuid>"
                }
            ]
        }
    }
}
```

---

### `signature_finished`

Todas as assinaturas do contrato foram concluídas.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 15:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/CONCESSIONARIA-CCB-OP000000000000001-signed.pdf"
            ]
        }
    }
}
```

---

### `disbursed`

Desembolso realizado com sucesso. Recursos transferidos para a conta indicada.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 16:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001"
        },
        "disbursement_date": "2025-05-10"
    }
}
```

---

### `canceled`

Operação cancelada. Caso a operação não seja assinada ou averbada até a última opção de data de desembolso, o parceiro recebe este webhook informando o cancelamento.

**Payload**

```json
{
    "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>"
    }
}
```

#### Enumeradores de cancelamento

| Enumerador | Descrição |
|------------|-----------|
| requester_request | Cancelado a pedido do parceiro |
| expiration | Vencimento da operação |
| regulatory | Cancelamento regulatório |
| duplicity | Operação duplicada |
| internal_error | Erro interno |

---

### `settled`

Operação liquidada. Todas as parcelas foram pagas e a operação está encerrada.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "settled",
    "webhook_type": "debt",
    "event_datetime": "2026-05-15 10:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001"
        },
        "settlement_date": "2026-05-15"
    }
}
```

---

:::info Configuração
O Webhook de Garantia Veicular requer URLs cadastradas. Consulte o time de onboarding para configurar.
:::

---

# Manual de Garantia Veicular

URL: /documentation/manual_garantia_veicular/

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

:::danger 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.
:::

:::info Reenvio de Webhooks
É possível consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

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. O processo é acompanhado via endpoints de consulta (GET) e webhooks.

## Pré-requisitos

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

## Visão Geral do Fluxo

![Visão geral do fluxo de garantia veicular](/img/diagrams/manual-garantia-veicular-manual-garantia-veicular.svg)

1. **Simular** — Envie `POST /debt_simulation` com `collateral_type: "vehicle"` (ver [Simulação e Emissão](/documentation/garantia_veicular/simulacao_e_emissao));
2. **Criar a operação** — Envie `POST /debt` incluindo os dados do veículo no objeto `collaterals` (ver [Simulação e Emissão](/documentation/garantia_veicular/simulacao_e_emissao));
3. **QI Tech registra o gravame** — Após a assinatura do contrato, a QI Tech envia automaticamente a inclusão de gravame ao SNG/B3. Webhooks enviados: `pending_reservation_confirmation` → `reserved`;
4. **Desembolso** — Após a confirmação do gravame (`reserved`), a QI Tech realiza o desembolso (transferência de recursos) para a conta informada;
5. **QI Tech registra o contrato** — A QI Tech envia automaticamente o registro de contrato ao DETRAN/Registradora. Webhooks enviados: `pending_registration_confirmation` → `registered`;
6. **QI Tech envia a imagem do contrato** — A QI Tech realiza o envio da imagem ao DETRAN/Registradora;
7. **Acompanhar o progresso** — Consulte a reserva (gravame) e registro (contrato) a qualquer momento via endpoints GET (ver [Consultas](/documentation/garantia_veicular/consultas));
8. **Receber notificações** — Os webhooks de gravame usam o tipo `laas.vehicle_collateral.reservation.status_change` (SNG/B3) e os de contrato usam `laas.vehicle_collateral.contract.status_change` (DETRAN) (ver [Webhooks](/documentation/garantia_veicular/webhooks)).

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

:::info 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
:::