Módulo Indicação de Condutores — API v2 (Beta)
Este módulo está em beta. A API pode sofrer alterações antes da versão final.
Submeta indicações formais de condutores para um AIT (Auto de Infração de Trânsito) diretamente pela API. O processamento é assíncrono: você envia a indicação e recebe o resultado via webhook quando concluído.
O que dá para fazer
| Ação | Endpoint | Quando usar |
|---|---|---|
| Enviar indicação | POST /v2/driver-indications | Submeter a indicação formal de um condutor para um AIT |
| Consultar por AIT | GET /v2/driver-indications/{ait} | Verificar o estado atual de uma indicação sem webhook, ou reconciliar |
Este módulo usa a mesma autenticação HMAC-SHA256 da API v1. Veja o Guia de Autenticação HMAC.
Antes de usar este módulo, certifique-se de ter:
- clientId — ID da sua empresa. Obtenha via módulo de Empresas.
- driverId — Condutor cadastrado via API de Condutores.
- Documentos — Arquivos disponíveis via URL HTTPS.
- Credenciais HMAC — Access Token e Secret Key fornecidos no onboarding.
Fluxo geral
1. Autenticação → HMAC-SHA256 (ver guia de autenticação)
2. Enviar indicação → POST /v2/driver-indications → 201 (status: received)
↓ [processamento assíncrono em background]
3. Validar documentos → status: processing
4. Confirmar indicação → status: confirmed
5. Enviar ao órgão → status: sent_to_organ
6. Resposta do órgão → status: accepted | rejected | wrong_documents
7. Receber resultado → Webhook (ou GET /v2/driver-indications/{ait})
O POST retorna 201 imediatamente após enfileirar a indicação. Todas as etapas 3–6 ocorrem de forma assíncrona; sua aplicação é notificada via webhook a cada mudança de estado relevante.
Como funciona, em outras palavras
Ao enviar a indicação, a API responde na hora com o status: received — o pedido foi aceito e entrou na fila. A partir daí, o trabalho acontece em segundo plano: os documentos são validados, a indicação é confirmada e enviada ao órgão de trânsito, que responde com o resultado final.
Você não precisa ficar perguntando se terminou: a cada mudança de estado, sua aplicação recebe um webhook. É como protocolar um documento e receber um e-mail de confirmação quando ele for processado — em vez de ligar a cada cinco minutos para saber a novidade. Se preferir, também dá para consultar o estado atual a qualquer momento pelo AIT.
Status da indicação
Uma indicação percorre os seguintes estados:
| Status | Descrição |
|---|---|
received | Indicação recebida e na fila de processamento |
processing | Documentos sendo validados |
confirmed | Documentos validados, aguardando envio ao órgão |
sent_to_organ | Enviado ao órgão de trânsito |
accepted | Aceito pelo órgão ✅ |
rejected | Rejeitado pelo órgão ❌ |
wrong_documents | Documentação incorreta — pode ser corrigida e reenviada |
error | Erro no processamento — pode ser reenviado |
cancelled | Indicação cancelada |
Transições de status
Estados terminais (accepted, rejected, cancelled): nenhuma ação adicional é possível.
Estados recuperáveis (error, wrong_documents): a indicação pode ser corrigida e submetida novamente. No status wrong_documents, o payload do webhook inclui "can_reindicate": true como indicação explícita.
Enviar indicação
/v2/driver-indicationsEnvia a indicação formal de um condutor para o AIT. O retorno 201 com status: "received" confirma que a indicação foi aceita e está em fila.
Campos obrigatórios
| Campo | Tipo | Descrição |
|---|---|---|
clientId | number | ID da sua empresa. Obtenha via módulo de Empresas. |
notificationId | string | ID da notificação no órgão de trânsito |
driverId | string | ID do condutor cadastrado na API de Condutores |
vehicleType | VEHICLE_OWNED | VEHICLE_RENTED | Tipo do veículo: próprio ou locado |
signerType | OWNER_SIGNATURE | PROXY_SIGNATURE | Assinante: proprietário ou procurador |
files | object | Arquivos da indicação (ver tabela abaixo) |
Arquivos (files)
| Campo | Obrigatório | Condição | Descrição |
|---|---|---|---|
nominateFormFile | Sim | Sempre | Formulário de indicação assinado (URL) |
companyRegistrationFile | Sim | Sempre | Contrato social (URL) |
licenseFile | Sim | Sempre | CNH do condutor (documento completo) |
cardIdFile | Sim | Sempre | CNH ou RG do proprietário/procurador |
leaseContractFile | Condicional | vehicleType=VEHICLE_RENTED | Contrato de locação |
legalRepresentationFile | Condicional | signerType=PROXY_SIGNATURE | CNH ou RG do procurador |
additionalDriverFineIndicationFile | Opcional | — | Documento adicional de suporte |
Campos opcionais
| Campo | Tipo | Descrição |
|---|---|---|
saveDefaultFileTypes | string[] | Salvar arquivos como padrão da empresa para próximas indicações. Valores: COMPANY_REGISTRATION_FILE, LEASE_CONTRACT_FILE |
Exemplo de requisição
curl -X POST \
https://api.sandbox.v2.frota162.com.br/v2/driver-indications \
-H 'Authorization: Basic {ACCESS_TOKEN}' \
-H 'Key: {HMAC_SIGNATURE}' \
-H 'Content-Type: application/json' \
-d '{
"clientId": 789,
"notificationId": "123456789",
"driverId": "987654321",
"vehicleType": "VEHICLE_OWNED",
"signerType": "OWNER_SIGNATURE",
"files": {
"nominateFormFile": "https://storage.example.com/nominate-form.pdf",
"companyRegistrationFile": "https://storage.example.com/company-registration.pdf",
"licenseFile": "https://storage.example.com/license.jpg",
"cardIdFile": "https://storage.example.com/card-id.jpg"
}
}'
Resposta (201 Created)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "received",
"ait": "SP-2024-000001",
"createdAt": "2026-05-14T10:00:00.000Z"
}
O status: "received" confirma que a indicação foi aceita e está em fila. O resultado final chega via webhook.
Consultar indicação pelo AIT
/v2/driver-indications/{ait}Use para verificar o estado atual de uma indicação quando não houver webhook configurado ou para reconciliação.
curl -X GET \
https://api.sandbox.v2.frota162.com.br/v2/driver-indications/SP-2024-000001 \
-H 'Authorization: Basic {ACCESS_TOKEN}' \
-H 'Key: {HMAC_SIGNATURE}'
Resposta (200 OK)
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"ait": "SP-2024-000001",
"notificationId": "123456789",
"carPlate": "ABC1234",
"driverId": "987654321",
"status": "sent_to_organ",
"indicationLimitDate": "2026-06-14T00:00:00.000Z",
"indicationStartedAt": "2026-05-14T10:05:00.000Z",
"communicationsSent": 1,
"responses": [
{
"id": "resp001",
"status": "received",
"createdAt": "2026-05-14T10:00:00.000Z",
"updatedAt": "2026-05-14T10:00:00.000Z"
},
{
"id": "resp002",
"status": "sent_to_organ",
"createdAt": "2026-05-14T10:05:00.000Z",
"updatedAt": "2026-05-14T10:05:00.000Z"
}
],
"createdAt": "2026-05-14T10:00:00.000Z",
"updatedAt": "2026-05-14T10:05:00.000Z"
}
indicationLimitDate— prazo final para realizar a indicação junto ao órgão. Após essa data, o órgão pode recusar a indicação.
Receber atualizações via webhook
Configure uma URL global de webhook via Guia de Webhooks. Sua URL receberá notificações para todas as mudanças de status da indicação — incluindo as respostas do órgão (sent_to_organ, accepted, rejected, wrong_documents).
Payload:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"ait": "SP-2024-000001",
"driver_id": "987654321",
"company_id": 789,
"event_type": "DRIVER_INDICATION",
"status": "accepted",
"vehicle_type": "VEHICLE_OWNED",
"signer_type": "OWNER_SIGNATURE",
"notification_id": "123456789",
"created_at": "2026-05-14T10:00:00.000Z",
"updated_at": "2026-05-14T10:30:00.000Z"
}
wrong_documentsQuando status for wrong_documents, o payload inclui o campo adicional "can_reindicate": true, indicando que a indicação pode ser corrigida e reenviada.
Erros
A API v2 retorna erros no padrão RFC 7807 Problem Details — completamente diferente do formato fbk_xxx da v1. Veja o Guia de Tratamento de Erros para a referência completa.
Todos os erros retornam o seguinte formato:
{
"type": "urn:frota162-api-v2:error:{tipo}",
"title": "Título do erro",
"status": 401,
"detail": "Descrição específica do problema",
"instance": "/v2/driver-indications",
"traceId": "abc123def456"
}
Header Authorization ausente (401)
{
"type": "urn:frota162-api-v2:error:unauthorized",
"title": "Unauthorized Access",
"status": 401,
"detail": "Missing required header: Authorization",
"instance": "/v2/driver-indications",
"traceId": "abc123"
}
Causa: Header Authorization: Basic {ACCESS_TOKEN} não enviado.
Header Key ausente (401)
{
"type": "urn:frota162-api-v2:error:unauthorized",
"title": "Unauthorized Access",
"status": 401,
"detail": "Missing required header: Key",
"instance": "/v2/driver-indications",
"traceId": "abc123"
}
Causa: Header Key: {HMAC_SIGNATURE} não enviado.
Assinatura HMAC inválida (401)
{
"type": "urn:frota162-api-v2:error:authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Invalid Key header",
"instance": "/v2/driver-indications",
"traceId": "abc123"
}
Causa: A assinatura HMAC no header Key não corresponde ao esperado. Recalcule usando HMAC-SHA256(ACCESS_TOKEN, SECRET_KEY).
Payload inválido (400)
{
"type": "urn:frota162-api-v2:error:validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid or missing parameters",
"instance": "/v2/driver-indications",
"traceId": "abc123"
}
Causa: Campo obrigatório ausente ou tipo incorreto. Verifique os campos da tabela Campos obrigatórios e os Arquivos condicionais.
Erro de validação de documentos (422)
{
"type": "urn:frota162-api-v2:error:indication-validation-error",
"title": "Indication Validation Error",
"status": 422,
"detail": "One or more documents failed validation",
"instance": "/v2/driver-indications",
"traceId": "abc123",
"validationErrors": [
{
"field": "licenseFile",
"message": "Document is expired or unreadable"
},
{
"field": "nominateFormFile",
"message": "Signature not found"
}
]
}
Causa: Um ou mais documentos foram rejeitados na validação. Inspecione o array validationErrors para identificar quais campos precisam ser corrigidos antes de reenviar.
Indicação não encontrada (404)
{
"type": "urn:frota162-api-v2:error:not-found",
"title": "Not Found",
"status": 404,
"detail": "Driver indication with AIT 'SP-2024-000001' not found",
"instance": "/v2/driver-indications/SP-2024-000001",
"traceId": "abc123"
}
Causa: Nenhuma indicação registrada para o AIT informado. Verifique se a indicação foi criada com sucesso via POST antes de consultar.
Tabela de referência rápida
| Status | type | Causa | Ação |
|---|---|---|---|
400 | validation-error | Campo obrigatório ausente ou inválido | Revisar payload |
401 | unauthorized | Header Authorization ou Key ausente | Adicionar os headers |
401 | authentication-failed | Assinatura HMAC inválida | Recalcular HMAC |
404 | not-found | AIT não encontrado | Verificar o código AIT |
422 | indication-validation-error | Documento rejeitado na validação | Verificar validationErrors |
429 | rate-limit-exceeded | Limite de requisições atingido | Aguardar e retentar |
500 | internal-server-error | Erro inesperado | Retentar com backoff |