Integre seu sistema à plataforma Frota162
A API Frota162 conecta o seu sistema à nossa plataforma de gestão de frotas. Veículos, condutores, multas e viagens passam a fluir entre os dois lados sem ninguém abrir o painel.
Você vai se deparar com três endereços diferentes ao longo da integração. Entender a diferença entre eles evita a maioria dos erros de início:
- 📡 API — é onde você envia as chamadas HTTP.
Exemplo:
https://api.v1.frota162.com.br/key/create-car - 🖥️ Plataforma (Sistema Web) — é onde você faz login para gerar credenciais e gerenciar sua conta.
Exemplo:
https://sistema.frota162.com.br/login - 📖 Documentação (este portal) — é onde você está agora, lendo os guias e a referência.
Exemplo:
https://docs.frota162.com
Regra prática: se você está escrevendo código que faz
curl,fetchouaxios, use a URL da API. Se você está num navegador gerando tokens ou gerenciando usuários, use a URL da Plataforma.
O que muda com a integração
Sem API, cada atualização exige login no painel, navegação manual e conciliação depois. Com API, seu sistema lê e escreve direto, e recebe aviso quando algo muda do nosso lado.
O que a API entrega
| Módulo | O que você consegue fazer |
|---|---|
| Veículos | Cadastrar, atualizar, listar, consultar e desativar |
| Empresas | Cadastrar, listar e desativar empresas, divisões e subdivisões |
| Usuários | Cadastrar e desativar usuários vinculados à conta |
| Condutores | Cadastrar, atualizar, listar, consultar e desativar |
| Viagens | Cadastrar, atualizar, listar, consultar e excluir |
| Multas e notificações | Vincular condutores a infrações e atualizar dados de pagamento |
| Webhooks | Receber eventos em tempo real (multas, notificações, IPVA) |
O módulo de Indicação de Motoristas (API v2) está em beta — o contrato pode mudar antes da versão final. Ver guia de Indicação de Motoristas
Qual API usar?
Operamos dois modelos de API simultaneamente. A diferença entre eles é histórica — cada um atende clientes integrados em momentos diferentes. As duas APIs não têm funcionalidades sobrepostas: elas se complementam, não se substituem.
| API v1 (Legado) | API v2 (Moderno) | |
|---|---|---|
| Tecnologia | PHP (Laravel) | Node.js (NestJS) — Partner Gateway |
| Identificação | Por usuário (email + senha) | Por empresa (Client ID + Client Secret) |
| Autenticação | HMAC SHA256 (Authorization: Basic + Key) recalculado a cada chamada | HMAC SHA256 (mesmo modelo da v1) |
| Cobertura | Completa — veículos, condutores, empresas, usuários, viagens, multas, webhooks, SSO | Apenas indicação de condutor (NIC) — nenhuma outra operação disponível |
| Status | Estável | Em evolução ativa |
| Se o cliente precisa de... | Use a... |
|---|---|
| Indicar condutor em multa (NIC) | API v2 — é a única funcionalidade disponível nela |
| Qualquer outra operação | API v1 — é a única que tem essas funcionalidades |
Para quem é este guia
Escrito para quem vai implementar a integração. Também serve para gestores e analistas que precisam saber o que a API cobre antes de decidir escopo — as seções com código podem ser repassadas ao time de desenvolvimento sem perda de contexto.
Ambientes
Dois ambientes isolados, com credenciais próprias. As chaves de um não funcionam no outro.
URLs da API (onde você envia as chamadas HTTP):
| Ambiente | Para que serve | API v1 | API v2 (beta) |
|---|---|---|---|
| Sandbox | Desenvolvimento e testes, dados fictícios | https://apidev.v1.frota162.com.br | https://api.sandbox.v2.frota162.com.br |
| Produção | Integração final, dados reais | https://api.v1.frota162.com.br | https://api.v2.frota162.com.br |
URLs da Plataforma (onde você gera credenciais e gerencia a conta):
| Ambiente | URL |
|---|---|
| Sandbox | https://sandbox.frota162.com.br |
| Produção | https://sistema.frota162.com.br |
Só migre para produção depois de validar o fluxo inteiro. Peça as credenciais de sandbox ao suporte antes de escrever a primeira linha.
Como a autenticação funciona
Você recebe duas credenciais: um ACCESS_TOKEN, que identifica sua conta, e uma SECRET_KEY, que nunca sai do seu servidor. A partir delas você deriva uma assinatura HMAC-SHA256 e envia três headers em toda requisição:
| Header | Valor |
|---|---|
Authorization | Basic {ACCESS_TOKEN} |
Key | assinatura derivada do token com a SECRET_KEY |
cache-control | no-cache |
Ela prova que você possui a SECRET_KEY. Ela não assina o conteúdo da requisição — corpo, URL e horário não entram no cálculo. Por isso o valor é constante enquanto o par de credenciais existir: na prática é uma segunda credencial derivada, e merece o mesmo cuidado de armazenamento que a primeira.
Detalhes, exemplos por linguagem e diagnóstico de erro: Autenticação.
O caminho para a primeira chamada
No fim desta seção você tem uma chamada autenticada respondendo 200 em sandbox, com dados da sua frota. Três passos: gerar credenciais, assinar a requisição, conferir a resposta.
Gere as credenciais no painel
Você precisa de duas chaves: um ACCESS_TOKEN e uma SECRET_KEY.
| Ambiente | Painel |
|---|---|
| Sandbox | https://sandbox.frota162.com.br/login |
| Produção | https://sistema.frota162.com.br/login |
- Entre no painel do ambiente que vai usar.
- Acesse Configurações → Usuários no menu lateral.
- Abra a edição do seu próprio usuário.
- Na seção Credenciais de API, use os botões Gerar Token e Gerar Secret Key.
- Clique em Ver para exibir os valores e em Copiar para levá-los ao seu ambiente.
Exporte as duas no shell antes de seguir:
export FROTA_ACCESS_TOKEN="seu_token"
export FROTA_SECRET_KEY="sua_chave_secreta"
Guarde as duas em variável de ambiente ou gerenciador de segredos. Nunca no código-fonte, nunca no navegador, nunca em log de requisição.
Faça a chamada assinada
A assinatura é um HMAC-SHA256 do ACCESS_TOKEN usando a SECRET_KEY como chave, com saída em hexadecimal. Três headers vão em toda requisição: Authorization, Key e cache-control.
- cURL
- Node.js
- Python
# chave = SECRET · mensagem = TOKEN · saída = hex
KEY=$(printf '%s' "$FROTA_ACCESS_TOKEN" \
| openssl dgst -sha256 -hmac "$FROTA_SECRET_KEY" \
| awk '{print $2}')
curl -s -w '\n%{http_code}\n' \
"https://apidev.v1.frota162.com.br/key/list-cars?pagination[page]=1&pagination[perpage]=10" \
-H "Authorization: Basic $FROTA_ACCESS_TOKEN" \
-H "Key: $KEY" \
-H 'cache-control: no-cache'
Use printf, não echo -n. O -n não é portável entre shells e, onde não funciona, o newline entra no cálculo e a assinatura sai errada sem nenhum aviso.
import crypto from 'node:crypto';
const TOKEN = process.env.FROTA_ACCESS_TOKEN;
const SECRET = process.env.FROTA_SECRET_KEY;
// chave = SECRET · mensagem = TOKEN · saída = hex
// inverter os dois primeiros é o erro nº 1 da integração
const key = crypto
.createHmac('sha256', SECRET)
.update(TOKEN)
.digest('hex');
const res = await fetch(
'https://apidev.v1.frota162.com.br/key/list-cars?pagination[page]=1&pagination[perpage]=10',
{
headers: {
Authorization: `Basic ${TOKEN}`,
Key: key,
'cache-control': 'no-cache',
},
},
);
console.log(res.status, await res.json());
import hashlib
import hmac
import os
import requests
token = os.environ['FROTA_ACCESS_TOKEN']
secret = os.environ['FROTA_SECRET_KEY'].encode()
# ordem: chave, mensagem, algoritmo · saída = hex
key = hmac.new(secret, token.encode(), hashlib.sha256).hexdigest()
res = requests.get(
'https://apidev.v1.frota162.com.br/key/list-cars',
params={'pagination[page]': 1, 'pagination[perpage]': 10},
headers={
'Authorization': f'Basic {token}',
'Key': key,
'cache-control': 'no-cache',
},
timeout=30,
)
print(res.status_code, res.json())
Confira o resultado
Status 200 e "error": false confirmam que a chamada passou. total é a contagem geral de veículos da conta; data traz os registros da página pedida.
node index.mjs
200 { cars: { current_page: 1, total: 42, ... }, error: false, code: 'fbk_200' }
A resposta
{
"cars": {
"current_page": 1,
"data": [
{
"id": 1,
"car_plate": "ABC1234",
"renavam": "00123456789",
"brand": "TOYOTA",
"model": "COROLLA",
"active": "1"
}
],
"total": 42,
"per_page": "10",
"last_page": 5
},
"error": false,
"code": "fbk_200"
}
Como percorrer as demais páginas: Paginação.
Quando vem erro em vez de dados
O erro do primeiro dia é quase sempre de autenticação, e todos os casos abaixo devolvem o mesmo fbk_001 — a mensagem não distingue a causa.
{
"message": "Não autorizado",
"error": true,
"code": "fbk_001"
}
| Sintoma | Causa provável | Como resolver |
|---|---|---|
fbk_001 constante | Chave e mensagem invertidas no HMAC | A chave é a SECRET_KEY, a mensagem é o ACCESS_TOKEN |
fbk_001 constante | Assinatura em base64 | A API só aceita hexadecimal (digest('hex')) |
fbk_001 constante | Algoritmo errado | Precisa ser sha256 — não sha1, não md5 |
fbk_001 intermitente | Newline ou espaço no valor lido do ambiente | Aplique trim() no token e na chave |
| Resposta antiga ou inesperada | Header cache-control ausente | Adicione cache-control: no-cache |
fbk_002 | Conta sem permissão para a empresa | Não é problema de assinatura. Fale com o suporte |
Confirme também que a URL aponta para sandbox (apidev) e que as credenciais são as do mesmo ambiente — chave de produção em sandbox devolve fbk_001.
Lista completa de códigos: Tratamento de erros.