Módulos v2

Módulo Indicação de Condutores — API v2

12 min de leituraVale para v2

Quando um veículo da empresa leva uma multa, a empresa tem um prazo para informar ao órgão de trânsito quem estava dirigindo. Isso é a indicação de condutor. Sem ela, os pontos vão para o proprietário do veículo.

Este módulo faz a indicação pela API: você informa a multa, o condutor e os documentos, e o resultado do órgão chega para o seu sistema por webhook.

A rota POST /v2/driver-indications será desligada em 24/11/2026

Depois dessa data, ela deixa de responder. No lugar dela entra o fluxo por etapas, que mostra em que ponto está cada indicação e devolve os erros na hora. Se você já usa a rota antiga, veja por que mudou e como migrar.

Como funciona

A indicação é feita em quatro etapas, nesta ordem:

Criar a indicação. Você informa qual multa quer indicar. A API responde com a lista de documentos que o órgão exige.
Escolher o condutor. Você informa quem estava dirigindo.
Enviar os documentos. Um documento por vez, até não faltar nenhum.
Confirmar. A indicação é enviada ao órgão de trânsito.

Se algo estiver errado em qualquer etapa, a API avisa na hora, e você corrige antes de seguir. Depois da confirmação, o órgão analisa a indicação, o que pode levar alguns dias, e o resultado chega por webhook.

Para quem é cada parte desta página

Visão geral: até a seção Status da indicação está tudo o que você precisa para entender o processo.

Implementação: a partir de Referência técnica das rotas estão endpoints, payloads, erros e um exemplo completo em Python, PHP, Node.js e cURL.

Rotas disponíveis

Ação	Endpoint	Descrição
Criar rascunho	`POST /v2/driver-indications/draft`	Cria a indicação e retorna os arquivos pendentes
Vincular condutor	`PATCH /v2/driver-indications/{id}/driver`	Associa ou substitui o condutor do rascunho
Enviar arquivo	`POST /v2/driver-indications/{id}/files`	Envia um arquivo por chamada
Confirmar indicação	`POST /v2/driver-indications/{id}/confirm`	Envia ao órgão e avança para `sent_to_organ`
Consultar por ID	`GET /v2/driver-indications/{id}`	Verifica o estado atual da indicação
~~Enviar indicação (antiga)~~	~~`POST /v2/driver-indications`~~	⛔ Será desligada — não utilizar

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.

Sequência de chamadas

Cada etapa é uma chamada separada. Se houver erro de validação ou de regra de negócio, ele volta na resposta da própria chamada, sem esperar webhook.

POST  /v2/driver-indications/draft        →  201 { id, status: "draft", requiredFiles: [...] }
PATCH /v2/driver-indications/{id}/driver  →  200 { id, status: "draft", driverId, requiredFiles: [...] }
POST  /v2/driver-indications/{id}/files   →  200 { fileId, fileType, missing: [...] }  (repetir por arquivo)
POST  /v2/driver-indications/{id}/confirm →  200 { id, status: "sent_to_organ" }
GET   /v2/driver-indications/{id}         →  200 { ... }  (consulta opcional)

   Resposta do órgão  →  Webhook driver_indication  (accepted | rejected | wrong_documents | cancelled | failed)

Quer testar sem dados reais? Veja o Ambiente de testes (sandbox).

Ainda usa a rota antiga POST /v2/driver-indications? Veja Como migrar da rota antiga.

Status da indicação

Ao longo do processo, a indicação passa por status diferentes. Quando chega a um status final, não muda mais.

draft ──confirm──▶ sent_to_organ ──▶ confirmed ──▶ accepted
                        │                │
                        └────────┬───────┘
                                 ├──▶ rejected
                                 ├──▶ wrong_documents ↺ corrigir e reenviar
                                 ├──▶ cancelled
                                 └──▶ failed

Status	O que significa	É o status final?	O que fazer
`draft`	Rascunho criado — condutor e/ou arquivos pendentes	Não	Completar as etapas e confirmar
`sent_to_organ`	Recebida pelo órgão, em análise	Não	Aguardar webhook
`confirmed`	Pré-confirmada pelo órgão, aguardando decisão final	Não	Aguardar webhook
`accepted`	Indicação aceita pelo órgão ✅	Sim	—
`rejected`	Indicação recusada — inclusive quando o próprio condutor recusa a indicação ❌	Sim	—
`wrong_documents`	Problema na documentação do condutor ou no formulário	Não	Corrigir e reenviar dentro do prazo
`cancelled`	Indicação cancelada ou prazo da multa expirado — não será mais avaliada	Sim	—
`failed`	Não foi possível concluir a indicação	Sim	Falar com o suporte

Status da rota antiga

received, processing e error só aparecem em indicações criadas pela rota antiga POST /v2/driver-indications.

Referência técnica das rotas

1. Criar rascunho

POST/v2/driver-indications/draft

Cria a indicação e retorna quais tipos de arquivo ainda precisam ser enviados antes da confirmação.

Body

Campo	Tipo	Obrigatório	Descrição
`clientId`	number	Sim	ID da empresa
`notificationId`	string	Sim	ID da notificação do AIT no órgão
`vehicleType`	`VEHICLE_OWNED` \| `VEHICLE_RENTED`	Sim	Veículo próprio ou locado
`signerType`	`OWNER_SIGNATURE` \| `PROXY_SIGNATURE`	Sim	Assinante: proprietário ou procurador

Exemplo de requisição

curl -X POST \
  https://api.sandbox.v2.frota162.com.br/v2/driver-indications/draft \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": 789,
    "notificationId": "1591837",
    "vehicleType": "VEHICLE_OWNED",
    "signerType": "OWNER_SIGNATURE"
  }'

Resposta `201 Created`

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "draft",
  "requiredFiles": [
    "NOMINATE_FORM_FILE",
    "COMPANY_REGISTRATION_FILE",
    "LICENSE_FILE",
    "CARD_ID_FILE"
  ]
}

Resposta `200 OK` — indicação já existe (idempotência)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "draft",
  "driverId": "987654321",
  "requiredFiles": ["NOMINATE_FORM_FILE"],
  "alreadyExists": true
}

Erros

Status	Nome	Causa
`404`	`NotificationNotFound`	Notificação inexistente
`409`	—	Indicação criada pela rota antiga, ainda em processamento
`422`	`DriverIndicationExpired`	Prazo da multa vencido
`500`	—	Erro inesperado do serviço de trânsito

2. Vincular condutor

PATCH/v2/driver-indications/{id}/driver

Associa ou substitui o condutor de um rascunho. Pode ser chamado mais de uma vez — em caso de erro, a indicação permanece no estado anterior (sem estado parcial).

Path param

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID retornado pelo `POST /draft`

Body

Campo	Tipo	Obrigatório	Descrição
`driverId`	string	Sim	ID do condutor a ser vinculado

Exemplo de requisição

curl -X PATCH \
  https://api.sandbox.v2.frota162.com.br/v2/driver-indications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/driver \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{ "driverId": "987654321" }'

Resposta `200 OK`

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "draft",
  "driverId": "987654321",
  "requiredFiles": ["NOMINATE_FORM_FILE", "COMPANY_REGISTRATION_FILE"]
}

Erros

Status	Nome	Causa
`400`	—	Payload inválido ou `id` não é UUID
`404`	`DriverIndicationNotFound`	Indicação não encontrada para esta organização
`409`	`DriverIndicationNotEditable`	Indicação fora do status `draft`
`422`	`DriverNotFound`	Condutor não encontrado
`422`	`DriverInvalidForIndication`	Condutor inválido; o `detail` lista os campos faltantes
`422`	`DriverLicenseFile`	Não foi possível processar o arquivo da CNH do condutor
`500`	—	Erro inesperado do serviço de trânsito

3. Enviar arquivo

POST/v2/driver-indications/{id}/files

Envia um arquivo por chamada via URL HTTPS. Repita para cada arquivo listado em requiredFiles. O campo missing na resposta indica os tipos que ainda faltam.

Path param

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID da indicação

Body (`Content-Type: application/json`)

Campo	Tipo	Obrigatório	Descrição
`fileType`	string	Sim	Tipo do arquivo (valores em `requiredFiles`): ex. `LICENSE_FILE`, `NOMINATE_FORM_FILE`
`url`	string	Sim	URL HTTPS pública do arquivo

Exemplo de requisição

curl -X POST \
  https://api.sandbox.v2.frota162.com.br/v2/driver-indications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileType": "LICENSE_FILE",
    "url": "https://storage.example.com/cnh.pdf"
  }'

Resposta `200 OK`

{
  "fileId": "legacy-file-12345",
  "fileType": "LICENSE_FILE",
  "missing": ["NOMINATE_FORM_FILE", "COMPANY_REGISTRATION_FILE"]
}

Quando missing retornar [], todos os arquivos foram enviados e a indicação está pronta para o confirm.

Erros

Status	Nome	Causa
`400`	—	Payload inválido, `fileType` desconhecido ou URL não-HTTPS
`400`	`FileTypeNotFound`	Tipo de arquivo não existe no órgão
`400`	`AdditionalFilesLimitExceeded`	Limite de arquivos desse tipo atingido
`404`	`DriverIndicationNotFound`	Indicação não encontrada para esta organização
`409`	`DriverIndicationNotEditable`	Indicação fora do status `draft`
`409`	`FileAlreadyUploaded`	Arquivo deste tipo já foi enviado — pule para o próximo
`415`	—	`Content-Type` diferente de `application/json`
`422`	`FileDownloadFailed`	Não foi possível baixar o arquivo da URL informada
`500`	—	Erro inesperado do serviço de trânsito

Arquivo já enviado (409)

Se receber 409 FileAlreadyUploaded, o arquivo já está registrado. Simplesmente pule para o próximo tipo em requiredFiles.

4. Confirmar indicação

POST/v2/driver-indications/{id}/confirm

Confirma a indicação e a envia ao órgão. Sem body. Após o confirm, o status avança para sent_to_organ e a resposta do órgão chegará via webhook.

Path param

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID da indicação

Exemplo de requisição

curl -X POST \
  https://api.sandbox.v2.frota162.com.br/v2/driver-indications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/confirm \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta `200 OK`

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "sent_to_organ"
}

Erros

Status	Nome	Causa
`400`	`AttachmentNotFound`	Falta arquivo obrigatório
`400`	`DriverIndicationNotEnabled`	Órgão não habilitado para esta indicação
`400`	`DriverIndicationNoFileChanged`	Nenhum arquivo alterado desde o último envio
`404`	`DriverIndicationNotFound`	Indicação não encontrada para esta organização
`409`	`DriverIndicationNotEditable`	Indicação já confirmada ou em outro estado
`422`	`DriverIndicationExpired`	Prazo da multa venceu após a criação do draft
`422`	`DriverNotFound`	Condutor não encontrado no órgão
`500`	—	Erro inesperado do serviço de trânsito

5. Consultar indicação por ID

GET/v2/driver-indications/{id}

Consulta o estado atual de uma indicação. Use para reconciliação ou para verificar o status sem depender de webhook. O {id} é o UUID devolvido pelo POST /draft — o mesmo usado nas demais rotas e nos webhooks. Indicações de outra organização retornam o mesmo 404 de uma inexistente, sem revelar que existem.

Path param

Parâmetro	Tipo	Descrição
`id`	string (UUID)	ID da indicação

Exemplo de requisição

curl -X GET \
  https://api.sandbox.v2.frota162.com.br/v2/driver-indications/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta `200 OK`

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mongoId": "507f1f77bcf86cd799439011",
  "notificationId": "1591837",
  "carPlate": "ABC1234",
  "orgCode": "ORG001",
  "clientId": "789",
  "status": "sent_to_organ",
  "indicationLimitDate": "2026-06-14T00:00:00.000Z",
  "indicationStartedAt": "2026-05-14T10:05:00.000Z",
  "communicationsSent": 1,
  "fileOptions": null,
  "driverId": "987654321",
  "responses": [
    {
      "id": "resp001",
      "status": "draft",
      "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 confirm retorna 422 DriverIndicationExpired.

Erros

Status	Nome	Causa
`400`	—	`id` não é UUID válido
`404`	`DriverIndicationNotFound`	Indicação não encontrada
`502`	—	Erro inesperado do serviço de trânsito

Exemplo completo

As quatro etapas de ponta a ponta, prontas para rodar no sandbox. O notificationId 99900010001 usa o cenário de sucesso: a indicação é aceita e o webhook chega com status: "accepted".

Assinatura HMAC

O header Key é a assinatura HMAC-SHA256 de cada requisição. Os exemplos deixam a função assinar para você implementar conforme o Guia de Autenticação HMAC. Assine exatamente o mesmo body que será enviado.

Código demonstrativo, não use em produção

Os exemplos abaixo existem só para mostrar a sequência das chamadas. Eles foram simplificados de propósito e não seguem boas práticas de produção. Antes de levar para a sua integração, trate pelo menos:

Credenciais: não deixe o token no código. Use variáveis de ambiente ou um cofre de segredos.
Retentativas: respostas 429 e 5xx devem ser retentadas com backoff. Os exemplos desistem no primeiro erro.
Retomada: guarde o id da indicação assim que o rascunho for criado, para continuar de onde parou se o processo cair no meio.
Logs e rastreio: registre o traceId das respostas de erro. É ele que o suporte vai pedir.
Webhook: o resultado final do órgão chega por webhook, que os exemplos não cobrem. Veja Receber atualizações via webhook.

Python
PHP
Node.js
cURL

import json
import requests

BASE_URL = "https://api.sandbox.v2.frota162.com.br"
ACCESS_TOKEN = "SEU_ACCESS_TOKEN"


class ApiError(Exception):
    def __init__(self, problem):
        self.status = problem.get("status")
        self.error_name = problem.get("errorName")
        super().__init__(f"{self.status} {self.error_name}: {problem.get('detail')}")


def assinar(metodo, caminho, body):
    """Gera a assinatura do header `Key`. Implemente conforme o Guia de Autenticação HMAC."""
    raise NotImplementedError


def chamar(metodo, caminho, payload=None):
    body = json.dumps(payload) if payload is not None else ""
    headers = {
        "Authorization": f"Basic {ACCESS_TOKEN}",
        "Key": assinar(metodo, caminho, body),
        "Content-Type": "application/json",
    }
    resp = requests.request(metodo, BASE_URL + caminho, data=body or None, headers=headers, timeout=30)
    if resp.status_code >= 400:
        raise ApiError(resp.json())
    return resp.json()


# URL HTTPS de cada documento que você pode enviar
DOCUMENTOS = {
    "NOMINATE_FORM_FILE": "https://seu-storage.com/formulario.pdf",
    "COMPANY_REGISTRATION_FILE": "https://seu-storage.com/contrato-social.pdf",
    "LICENSE_FILE": "https://seu-storage.com/cnh.pdf",
    "CARD_ID_FILE": "https://seu-storage.com/documento.pdf",
}

# 1. Criar a indicação
draft = chamar("POST", "/v2/driver-indications/draft", {
    "clientId": 789,
    "notificationId": "99900010001",
    "vehicleType": "VEHICLE_OWNED",
    "signerType": "OWNER_SIGNATURE",
})
indicacao_id = draft["id"]

# 2. Vincular o condutor (a resposta traz a lista atualizada de documentos)
driver = chamar("PATCH", f"/v2/driver-indications/{indicacao_id}/driver", {"driverId": "987654321"})

# 3. Enviar os documentos, um por chamada
for tipo in driver["requiredFiles"]:
    try:
        chamar("POST", f"/v2/driver-indications/{indicacao_id}/files", {
            "fileType": tipo,
            "url": DOCUMENTOS[tipo],
        })
    except ApiError as erro:
        if erro.error_name != "FileAlreadyUploaded":  # já enviado: segue para o próximo
            raise

# 4. Confirmar e enviar ao órgão
confirmacao = chamar("POST", f"/v2/driver-indications/{indicacao_id}/confirm")
print(confirmacao["status"])  # sent_to_organ

<?php

const BASE_URL = 'https://api.sandbox.v2.frota162.com.br';
const ACCESS_TOKEN = 'SEU_ACCESS_TOKEN';

class ApiError extends Exception
{
    public function __construct(public array $problem)
    {
        parent::__construct(sprintf('%s %s: %s', $problem['status'] ?? '', $problem['errorName'] ?? '', $problem['detail'] ?? ''));
    }
}

// Gera a assinatura do header `Key`. Implemente conforme o Guia de Autenticação HMAC.
function assinar(string $metodo, string $caminho, string $body): string
{
    throw new LogicException('Implemente a assinatura HMAC');
}

function chamar(string $metodo, string $caminho, ?array $payload = null): array
{
    $body = $payload !== null ? json_encode($payload) : '';

    $ch = curl_init(BASE_URL . $caminho);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $metodo,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_POSTFIELDS => $body,
        CURLOPT_HTTPHEADER => [
            'Authorization: Basic ' . ACCESS_TOKEN,
            'Key: ' . assinar($metodo, $caminho, $body),
            'Content-Type: application/json',
        ],
    ]);
    $resposta = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status >= 400) {
        throw new ApiError($resposta);
    }
    return $resposta;
}

// URL HTTPS de cada documento que você pode enviar
$documentos = [
    'NOMINATE_FORM_FILE' => 'https://seu-storage.com/formulario.pdf',
    'COMPANY_REGISTRATION_FILE' => 'https://seu-storage.com/contrato-social.pdf',
    'LICENSE_FILE' => 'https://seu-storage.com/cnh.pdf',
    'CARD_ID_FILE' => 'https://seu-storage.com/documento.pdf',
];

// 1. Criar a indicação
$draft = chamar('POST', '/v2/driver-indications/draft', [
    'clientId' => 789,
    'notificationId' => '99900010001',
    'vehicleType' => 'VEHICLE_OWNED',
    'signerType' => 'OWNER_SIGNATURE',
]);
$id = $draft['id'];

// 2. Vincular o condutor (a resposta traz a lista atualizada de documentos)
$driver = chamar('PATCH', "/v2/driver-indications/{$id}/driver", ['driverId' => '987654321']);

// 3. Enviar os documentos, um por chamada
foreach ($driver['requiredFiles'] as $tipo) {
    try {
        chamar('POST', "/v2/driver-indications/{$id}/files", [
            'fileType' => $tipo,
            'url' => $documentos[$tipo],
        ]);
    } catch (ApiError $erro) {
        if (($erro->problem['errorName'] ?? '') !== 'FileAlreadyUploaded') { // já enviado: segue para o próximo
            throw $erro;
        }
    }
}

// 4. Confirmar e enviar ao órgão
$confirmacao = chamar('POST', "/v2/driver-indications/{$id}/confirm");
echo $confirmacao['status'], PHP_EOL; // sent_to_organ

// Node.js 18+ (fetch nativo)
const BASE_URL = 'https://api.sandbox.v2.frota162.com.br';
const ACCESS_TOKEN = 'SEU_ACCESS_TOKEN';

class ApiError extends Error {
  constructor(problem) {
    super(`${problem.status} ${problem.errorName}: ${problem.detail}`);
    this.status = problem.status;
    this.errorName = problem.errorName;
  }
}

// Gera a assinatura do header `Key`. Implemente conforme o Guia de Autenticação HMAC.
function assinar(metodo, caminho, body) {
  throw new Error('Implemente a assinatura HMAC');
}

async function chamar(metodo, caminho, payload) {
  const body = payload !== undefined ? JSON.stringify(payload) : '';
  const resp = await fetch(BASE_URL + caminho, {
    method: metodo,
    body: body || undefined,
    headers: {
      Authorization: `Basic ${ACCESS_TOKEN}`,
      Key: assinar(metodo, caminho, body),
      'Content-Type': 'application/json',
    },
    signal: AbortSignal.timeout(30_000),
  });
  const dados = await resp.json();
  if (!resp.ok) throw new ApiError(dados);
  return dados;
}

// URL HTTPS de cada documento que você pode enviar
const DOCUMENTOS = {
  NOMINATE_FORM_FILE: 'https://seu-storage.com/formulario.pdf',
  COMPANY_REGISTRATION_FILE: 'https://seu-storage.com/contrato-social.pdf',
  LICENSE_FILE: 'https://seu-storage.com/cnh.pdf',
  CARD_ID_FILE: 'https://seu-storage.com/documento.pdf',
};

async function main() {
  // 1. Criar a indicação
  const draft = await chamar('POST', '/v2/driver-indications/draft', {
    clientId: 789,
    notificationId: '99900010001',
    vehicleType: 'VEHICLE_OWNED',
    signerType: 'OWNER_SIGNATURE',
  });
  const id = draft.id;

  // 2. Vincular o condutor (a resposta traz a lista atualizada de documentos)
  const driver = await chamar('PATCH', `/v2/driver-indications/${id}/driver`, {
    driverId: '987654321',
  });

  // 3. Enviar os documentos, um por chamada
  for (const tipo of driver.requiredFiles) {
    try {
      await chamar('POST', `/v2/driver-indications/${id}/files`, {
        fileType: tipo,
        url: DOCUMENTOS[tipo],
      });
    } catch (erro) {
      if (erro.errorName !== 'FileAlreadyUploaded') throw erro; // já enviado: segue para o próximo
    }
  }

  // 4. Confirmar e enviar ao órgão
  const confirmacao = await chamar(
    'POST',
    `/v2/driver-indications/${id}/confirm`,
  );
  console.log(confirmacao.status); // sent_to_organ
}

main().catch(erro => {
  console.error(erro.message);
  process.exit(1);
});

BASE=https://api.sandbox.v2.frota162.com.br/v2/driver-indications
# Gere o header Key (HMAC) de cada chamada conforme o Guia de Autenticação HMAC.

# 1. Criar a indicação (guarde o "id" da resposta)
curl -X POST "$BASE/draft" \
  -H 'Authorization: Basic {ACCESS_TOKEN}' -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{"clientId": 789, "notificationId": "99900010001", "vehicleType": "VEHICLE_OWNED", "signerType": "OWNER_SIGNATURE"}'

# 2. Vincular o condutor
curl -X PATCH "$BASE/{id}/driver" \
  -H 'Authorization: Basic {ACCESS_TOKEN}' -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{"driverId": "987654321"}'

# 3. Enviar cada documento de requiredFiles (repita por tipo)
curl -X POST "$BASE/{id}/files" \
  -H 'Authorization: Basic {ACCESS_TOKEN}' -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{"fileType": "LICENSE_FILE", "url": "https://seu-storage.com/cnh.pdf"}'

# 4. Confirmar
curl -X POST "$BASE/{id}/confirm" \
  -H 'Authorization: Basic {ACCESS_TOKEN}' -H 'Key: {HMAC_SIGNATURE}'

Como migrar da rota antiga

Por que a rota mudou

Na rota antiga, a indicação inteira era enviada numa única chamada e processada em segundo plano. Se algo desse errado, você só ficava sabendo depois, por webhook, e nem sempre era possível saber em que ponto a indicação tinha parado: se o problema estava na multa, no condutor ou em algum documento.

No fluxo por etapas, você acompanha a indicação passo a passo:

Cada etapa responde na hora. Você sabe exatamente qual etapa falhou e por quê.
Você corrige só o que deu errado. Se o envio de um documento falhar, basta reenviar aquele documento, sem refazer a indicação inteira.
O status é sempre claro. Antes da confirmação, a indicação fica em draft, e o campo missing mostra o que ainda falta.

O que muda na integração

A rota antiga fazia tudo em uma única chamada e só avisava erros por webhook. No fluxo por etapas, cada etapa é uma chamada separada e os erros voltam na hora.

Rota antiga (`POST /v2/driver-indications`)	Fluxo por etapas
`clientId`, `notificationId`, `vehicleType`, `signerType`	`POST /v2/driver-indications/draft` (mesmos campos)
`driverId`	`PATCH /v2/driver-indications/{id}/driver`
Objeto `files` (todos os arquivos juntos)	`POST /v2/driver-indications/{id}/files` — um arquivo por chamada, usando os tipos em `requiredFiles`
Processamento e envio ao órgão em segundo plano	`POST /v2/driver-indications/{id}/confirm`
Erros só via webhook	Erros na resposta de cada chamada (RFC 7807)
Resultado do órgão via webhook	Resultado do órgão via webhook (sem mudança)

Não dependa da lista fixa de arquivos

No fluxo por etapas, os arquivos obrigatórios (inclusive os condicionais por vehicleType e signerType) vêm em requiredFiles na resposta do draft. Envie o que estiver lá e confira o campo missing até retornar [].

Rota antiga — referência (será desligada em 24/11/2026)

POST/v2/driver-indications

Será desligada em 24/11/2026 — não utilize

Esta rota será desligada e não deve ser usada em novas integrações. Quem ainda a utiliza deve migrar para o fluxo por etapas — veja Como migrar da rota antiga. A documentação abaixo existe apenas para apoiar a migração.

Ver referência da rota antiga

Fluxo

POST /v2/driver-indications  →  201 { id, status: "received", createdAt }
   ↓ [processamento assíncrono em background]
Validar documentos     →  status: processing
Confirmar indicação    →  status: confirmed
Enviar ao órgão        →  status: sent_to_organ
Resposta do órgão      →  Webhook (accepted | rejected | wrong_documents)

Enfileira a indicação. Retorna 201 imediatamente com status: received. Todas as demais etapas ocorrem de forma assíncrona; o resultado chega exclusivamente via webhook.

Body

Campo	Tipo	Obrigatório	Descrição
`clientId`	number	Sim	ID da empresa
`notificationId`	string	Sim	ID da notificação do AIT
`driverId`	string	Sim	ID do condutor
`vehicleType`	`VEHICLE_OWNED` \| `VEHICLE_RENTED`	Sim	Tipo do veículo
`signerType`	`OWNER_SIGNATURE` \| `PROXY_SIGNATURE`	Sim	Assinante
`files`	object	Sim	Arquivos da indicação (ver abaixo)
`saveDefaultFileTypes`	string[]	Não	Salvar arquivos como padrão da empresa

Arquivos (files):

Campo	Obrigatório	Condição
`nominateFormFile`	Sim	Sempre
`companyRegistrationFile`	Sim	Sempre
`licenseFile`	Sim	Sempre
`cardIdFile`	Sim	Sempre
`leaseContractFile`	Condicional	`vehicleType=VEHICLE_RENTED`
`legalRepresentationFile`	Condicional	`signerType=PROXY_SIGNATURE`
`additionalDriverFineIndicationFile`	Opcional	—

Resposta `201 Created`

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "received",
  "createdAt": "2026-05-14T10:00:00.000Z"
}

Receber atualizações via webhook

Configure uma URL global de webhook via Guia de Webhooks. Sua URL receberá notificações a cada mudança de status relevante — incluindo as respostas do órgão.

{
  "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": "1591837",
  "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 can_reindicate, que indica se a indicação ainda pode ser corrigida e reenviada dentro do prazo.

Ambiente de testes (sandbox)

No ambiente sandbox, a indicação de condutor não aciona órgãos de trânsito nem consome dados reais: um catálogo determinístico de prefixos no notificationId devolve desfechos previsíveis para você testar todas as etapas e os webhooks da sua integração. Mesmo prefixo → mesmo resultado, sempre.

Como o catálogo funciona

Resolução por prefixo: o sandbox identifica o cenário desejado pelos primeiros 7 dígitos do notificationId (faixa 99900xx).
Sufixo livre: você pode adicionar qualquer sequência numérica ao final do prefixo (por exemplo, 99900010001 ou 99900019999 ambos acionam o cenário OKAC).
Identificador de AIT determinístico: o AIT gerado é T999 seguido dos 6 últimos dígitos do notificationId (ex.: 99900010042 → T999010042).
Isolamento completo: o sandbox reproduz as validações de negócio e o envio de webhooks, sem acionar órgãos externos.

Como usar o catálogo

Passo 1 — Criar rascunho (POST /draft): envie o notificationId iniciado pelo prefixo escolhido. Se o cenário for uma falha de criação (CRNF, CREX ou prefixo desconhecido), o erro HTTP é retornado imediatamente na resposta e o rascunho não permanece ativo.
Passo 2 — Vincular condutor (PATCH /{id}/driver): envie os dados do condutor. No cenário CRDR, a API retorna 422 DriverInvalidForIndication, mantendo o rascunho aberto para correção.
Passo 3 — Enviar arquivos (POST /{id}/files): envie os arquivos solicitados em requiredFiles. Cenários como FLTP (tipo inválido), FLDL (falha no download da URL) e FLDU (arquivo duplicado) retornam o erro correspondente.
Passo 4 — Confirmar indicação (POST /{id}/confirm): valida se todos os anexos foram enviados. Cenários como CFAT (anexo ausente) ou CFEX (prazo expirado no confirm) barram a confirmação. Em cenários de sucesso, a rota retorna 200 com status sent_to_organ.
Passo 5 — Webhook de desfecho: para indicações confirmadas, o webhook com o resultado final do órgão (accepted ou wrong_documents) é enviado ao seu endpoint configurado poucos segundos após a confirmação. Em produção, esse retorno do órgão pode levar dias.

Tabela de prefixos e cenários

Envie um notificationId com um destes prefixos:

Prefixo	Cenário	O que acontece	Execute até	HTTP	errorName	Webhook final
`9990001`	OKAC	Indicação aceita pelo órgão de trânsito	`draft` → `driver` → `files` → `confirm`	200	—	accepted
`9990002`	OKWD	Documentos recusados pelo órgão de trânsito (permite reindicação)	`draft` → `driver` → `files` → `confirm`	200	—	wrong_documents
`9990004`	CRNF	Notificação não encontrada no órgão de trânsito	`draft`	404	NotificationNotFound	—
`9990005`	CREX	Prazo da indicação expirado no momento da criação	`draft`	422	DriverIndicationExpired	—
`9990006`	CRDU	Repetir o POST /draft com o mesmo notificationId devolve o mesmo rascunho	`draft` ×2	200	—	accepted
`9990007`	CRDR	Condutor inválido para indicação ao vincular o condutor	`draft` → `driver`	422	DriverInvalidForIndication	—
`9990008`	FLTP	Tipo de arquivo não existe no órgão de trânsito	`draft` → `driver` → `files`	400	FileTypeNotFound	—
`9990009`	FLDL	Falha no download do arquivo a partir da URL fornecida	`draft` → `driver` → `files`	422	FileDownloadFailed	—
`9990010`	FLDU	Arquivo já enviado previamente (COMPANY_REGISTRATION_FILE)	`draft` → `driver` → `files`	409	FileAlreadyUploaded	—
`9990011`	CFAT	Anexo obrigatório ausente no momento da confirmação	`draft` → `driver` → `files` → `confirm`	400	AttachmentNotFound	—
`9990012`	CFEX	Prazo da indicação expirado no momento da confirmação	`draft` → `driver` → `files` → `confirm`	422	DriverIndicationExpired	—
qualquer outro	—	Prefixo não catalogado no sandbox	`draft`	422	SandboxUnknownScenario	—

Regras do catálogo:

O erro é forçado pelo prefixo: a coluna Execute até mostra quais chamadas fazer, em ordem. A última delas retorna o erro do cenário independentemente do payload. Por exemplo, em FLTP qualquer fileType válido retorna FileTypeNotFound, e em CFAT o confirm falha mesmo com todos os arquivos enviados.
Prefixo não catalogado: qualquer notificationId que não comece com um dos prefixos acima retorna erro 422 Unprocessable Entity com errorName: SandboxUnknownScenario e lista os prefixos válidos no detail.
Apenas fluxo por etapas: o sandbox suporta exclusivamente o fluxo por etapas (/draft, /{id}/driver, /{id}/files, /{id}/confirm e consulta /{id}). A rota antiga POST /v2/driver-indications não tem suporte a sandbox.
Somente sandbox: prefixos e AITs gerados são fictícios. Em produção, use identificadores reais de notificações.

Observações por cenário

CRDU: chame POST /draft duas vezes com os mesmos dados. A segunda chamada responde 200 OK (em vez de 201) com alreadyExists: true e o mesmo id do rascunho original.
OKWD: o webhook chega com can_reindicate: true, permitindo testar o fluxo de reindicação com documentos corrigidos.
CRDR: simula condutor inválido para indicação; o detail lista os campos faltantes (ex.: Missing fields: cnh, cpf). O rascunho continua aberto para vincular outro condutor.
FLDL: simula URL de arquivo inacessível ou expirada.

Horário do ambiente

O ambiente de sandbox opera de segunda a sexta-feira, das 07h às 19h (horário de Brasília, UTC−3). Fora deste horário, os serviços ficam suspensos e a primeira requisição pode sofrer um atraso temporário (cold start) enquanto a infraestrutura é inicializada.

Exemplos práticos

1. Criação com sucesso (draft)

curl -X POST https://api.sandbox.v2.frota162.com.br/v2/driver-indications/draft \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": 789,
    "notificationId": "99900010042",
    "vehicleType": "VEHICLE_OWNED",
    "signerType": "OWNER_SIGNATURE"
  }'

Resposta 201 Created:

{
  "id": "b7e6a2c4-1f3d-4e5a-9c8b-2d1e0f9a8b7c",
  "status": "draft",
  "requiredFiles": [
    "NOMINATE_FORM_FILE",
    "COMPANY_REGISTRATION_FILE",
    "LICENSE_FILE",
    "CARD_ID_FILE"
  ]
}

2. Webhook de indicação aceita (`OKAC`)

Após completar os arquivos e chamar POST /v2/driver-indications/{id}/confirm, o webhook chega em poucos segundos:

{
  "id": "b7e6a2c4-1f3d-4e5a-9c8b-2d1e0f9a8b7c",
  "ait": "T999010042",
  "driver_id": "987654321",
  "company_id": 789,
  "event_type": "DRIVER_INDICATION",
  "status": "accepted",
  "vehicle_type": "VEHICLE_OWNED",
  "signer_type": "OWNER_SIGNATURE",
  "notification_id": "99900010042",
  "created_at": "2026-09-25T10:00:00.000Z",
  "updated_at": "2026-09-25T10:00:15.000Z"
}

3. Webhook de documentos recusados (`OKWD`)

{
  "id": "c8f7b3d5-2e4a-5f6b-0d9c-3e2f1a0b9c8d",
  "ait": "T999020042",
  "driver_id": "987654321",
  "company_id": 789,
  "event_type": "DRIVER_INDICATION",
  "status": "wrong_documents",
  "can_reindicate": true,
  "vehicle_type": "VEHICLE_OWNED",
  "signer_type": "OWNER_SIGNATURE",
  "notification_id": "99900020042",
  "created_at": "2026-09-25T10:00:00.000Z",
  "updated_at": "2026-09-25T10:00:15.000Z"
}

4. Erro de validação imediato (ex.: arquivo duplicado `FLDU` — `409 Conflict`)

{
  "type": "urn:frota162-api-v2:error:conflict",
  "title": "Conflict",
  "status": 409,
  "errorName": "FileAlreadyUploaded",
  "detail": "A file of this type has already been uploaded",
  "instance": "/v2/driver-indications/b7e6a2c4-1f3d-4e5a-9c8b-2d1e0f9a8b7c/files",
  "traceId": "abc123def456"
}

5. Prefixo desconhecido (`422 Unprocessable Entity`)

Quando o notificationId não começa com nenhum prefixo catalogado:

{
  "type": "urn:frota162-api-v2:error:unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "errorName": "SandboxUnknownScenario",
  "detail": "The notificationId does not match any sandbox scenario. Valid prefixes: 9990001 (OKAC), 9990002 (OKWD), ...",
  "instance": "/v2/driver-indications/draft",
  "traceId": "abc123def456"
}

Erros — referência geral

Formato diferente da v1

A API v2 retorna erros no padrão RFC 7807 Problem Details. Veja o Guia de Tratamento de Erros para a referência completa.

{
  "type": "urn:frota162-api-v2:error:{tipo}",
  "title": "Título do erro",
  "status": 400,
  "detail": "Descrição específica do problema",
  "instance": "/v2/driver-indications/draft",
  "traceId": "abc123def456"
}

Status	Causa	Ação
`400`	Campo obrigatório ausente ou inválido	Revisar payload
`401`	Header `Authorization` ou `Key` ausente	Adicionar os headers
`401`	Assinatura HMAC inválida	Recalcular HMAC
`404`	Indicação não encontrada	Verificar o `id`
`409`	Conflito de estado (arquivo já enviado, etc)	Ver detalhes no `detail`
`415`	`Content-Type` inválido	Usar `application/json`
`422`	Validação de negócio reprovada	Ver `detail` ou `errors`
`429`	Limite de requisições atingido	Aguardar e retentar
`502`	Erro inesperado do serviço de trânsito	Retentar com backoff

Próximos passos

Consulta de CNHConsulte habilitações

Valide CNHs em tempo real com consulta individual ou em lote.

WebhooksReceba eventos em tempo real

Configure webhooks para receber atualizações de status das indicações.

Primeiros PassosComece a integrar

Configure seu ambiente e faça sua primeira chamada à API.

Como funciona​

Rotas disponíveis​

Sequência de chamadas​

Status da indicação​

Referência técnica das rotas​

1. Criar rascunho​

Body​

Exemplo de requisição​

Resposta 201 Created​

Resposta 200 OK — indicação já existe (idempotência)​

Erros​

2. Vincular condutor​

Path param​

Body​

Exemplo de requisição​

Resposta 200 OK​

Erros​

3. Enviar arquivo​

Path param​

Body (Content-Type: application/json)​

Exemplo de requisição​

Resposta 200 OK​

Erros​

4. Confirmar indicação​

Path param​

Exemplo de requisição​

Resposta 200 OK​

Erros​

5. Consultar indicação por ID​

Path param​

Exemplo de requisição​

Resposta 200 OK​

Erros​

Exemplo completo​

Como migrar da rota antiga​

Por que a rota mudou​

O que muda na integração​

Rota antiga — referência (será desligada em 24/11/2026)​

Fluxo​

Body​

Resposta 201 Created​

Receber atualizações via webhook​

Ambiente de testes (sandbox)​

Como o catálogo funciona​

Como usar o catálogo​

Tabela de prefixos e cenários​

Observações por cenário​

Exemplos práticos​

1. Criação com sucesso (draft)​

2. Webhook de indicação aceita (OKAC)​

3. Webhook de documentos recusados (OKWD)​

4. Erro de validação imediato (ex.: arquivo duplicado FLDU — 409 Conflict)​

5. Prefixo desconhecido (422 Unprocessable Entity)​

Erros — referência geral​

Próximos passos​

Como funciona

Rotas disponíveis

Sequência de chamadas

Status da indicação

Referência técnica das rotas

1. Criar rascunho

Body

Exemplo de requisição

Resposta `201 Created`

Resposta `200 OK` — indicação já existe (idempotência)

Erros

2. Vincular condutor

Path param

Body

Exemplo de requisição

Resposta `200 OK`

Erros

3. Enviar arquivo

Path param

Body (`Content-Type: application/json`)

Exemplo de requisição

Resposta `200 OK`

Erros

4. Confirmar indicação

Path param

Exemplo de requisição

Resposta `200 OK`

Erros

5. Consultar indicação por ID

Path param

Exemplo de requisição

Resposta `200 OK`

Erros

Exemplo completo

Como migrar da rota antiga

Por que a rota mudou

O que muda na integração

Rota antiga — referência (será desligada em 24/11/2026)

Fluxo

Body

Resposta `201 Created`

Receber atualizações via webhook

Ambiente de testes (sandbox)

Como o catálogo funciona

Como usar o catálogo

Tabela de prefixos e cenários

Observações por cenário

Exemplos práticos

1. Criação com sucesso (draft)

2. Webhook de indicação aceita (`OKAC`)

3. Webhook de documentos recusados (`OKWD`)

4. Erro de validação imediato (ex.: arquivo duplicado `FLDU` — `409 Conflict`)

5. Prefixo desconhecido (`422 Unprocessable Entity`)

Erros — referência geral

Próximos passos