Começando

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.

12 min de leituraVale para v1 e v2

Antes de tudo — três URLs que você vai usar

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, fetch ou axios, 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.

Dois caminhos: você chama a API quando precisa; a gente chama o seu endpoint quando algo acontece.

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)

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
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`

Comece por sandbox

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`

O que a assinatura prova

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 ou Gestão → 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:

terminal
export FROTA_ACCESS_TOKEN="seu_token"
export FROTA_SECRET_KEY="sua_chave_secreta"

A SECRET_KEY não deve sair do servidor

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

primeira-chamada.sh — roda como está
# 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.

index.mjs — arquivo completo
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());

primeira_chamada.py — arquivo completo
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.

Rodar

terminal
node index.mjs
200 { cars: { current_page: 1, total: 42, ... }, error: false, code: 'fbk_200' }

A resposta

200 OK
{
  "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.

401 · fbk_001
{
  "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.

Próximos passos

ReferênciaAutenticação HMAC

Exemplos em PHP, detalhes do cálculo e erros da v2.

MódulosVeículos e condutores

Endpoints por módulo, com exemplos de payload.

GuiasWebhooks

Receber eventos sem ficar consultando a API.

AjudaSuporte

Travou em algum passo? suporte@frota162.com.br

AjudaPerguntas frequentes

Respostas para as dúvidas mais comuns sobre a integração.

O que muda com a integração​

O que a API entrega​

Qual API usar?​

Para quem é este guia​

Ambientes​

Como a autenticação funciona​

O caminho para a primeira chamada​