Webhooks — Garantia Veicular
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.
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.
Webhooks de Garantia Veicular — Reserva (SNG/B3)
Notificações relacionadas ao registro de gravame no SNG/B3.
Estrutura Base do Webhook
{
"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) |
| 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
{
"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
{
"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
{
"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
{
"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 |
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)
Notificações relacionadas ao registro de contrato no DETRAN/Registradora.
Estrutura Base do Webhook
{
"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) |
| 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
{
"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
{
"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
{
"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
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.
waiting_signature
Contrato gerado e disponível para assinatura. A URL de assinatura é enviada neste webhook.
Payload
{
"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
{
"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
{
"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
{
"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
{
"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"
}
}
O Webhook de Garantia Veicular requer URLs cadastradas. Consulte o time de onboarding para configurar.