Módulo Indicação de Motoristas — API v2 (Beta)

Beta

Este módulo está em beta. A API pode sofrer alterações antes da versão final. Use em produção com cautela e acompanhe as Atualizações para mudanças.

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.

Autenticação

Este módulo usa a mesma autenticação HMAC-SHA256 da API v1. Veja o Guia de Autenticação HMAC.

Pré-requisitos

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.

---

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

POST /v2/driver-indications

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://apidev.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

GET /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://apidev.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"
}

Status wrong_documents

Quando status for wrong_documents, o payload inclui o campo adicional "can_reindicate": true, indicando que a indicação pode ser corrigida e reenviada.

---

Erros

Formato diferente da v1

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

---