Autenticação HMAC — Passo a Passo

Este guia mostra como calcular a assinatura HMAC e autenticar suas requisições à API Frota162. Se você ainda não tem as credenciais, veja a Visão Geral de Autenticação primeiro.

Headers obrigatórios

Toda requisição à API deve incluir estes headers:

Authorization: Basic {ACCESS_TOKEN}
Key: {HMAC_SIGNATURE}
cache-control: no-cache

O header cache-control: no-cache previne que proxies intermediários retornem uma resposta em cache em vez de encaminhar a requisição à API.

Como calcular a assinatura

A assinatura é um hash HMAC-SHA256 do ACCESS_TOKEN usando a SECRET_KEY como chave:

HMAC_SIGNATURE = HMAC-SHA256(ACCESS_TOKEN, SECRET_KEY)

Em termos simples: você passa o token pela "máquina de assinatura" (SHA-256) junto com a chave secreta, e o resultado é uma string hexadecimal que comprova a autenticidade da requisição.

Bom saber

A assinatura não muda enquanto suas credenciais forem as mesmas. Calcule uma vez e reutilize em todas as chamadas.

---

Exemplos de código

Node.js

const crypto = require('crypto');

function calcularHmac(accessToken, secretKey) {
  return crypto
    .createHmac('sha256', secretKey)
    .update(accessToken)
    .digest('hex');
}

const accessToken = process.env.FROTA_ACCESS_TOKEN;
const secretKey   = process.env.FROTA_SECRET_KEY;
const hmacKey     = calcularHmac(accessToken, secretKey);

const headers = {
  'Authorization': `Basic ${accessToken}`,
  'Key': hmacKey,
  'cache-control': 'no-cache',
};

PHP

$accessToken = getenv('FROTA_ACCESS_TOKEN');
$secretKey   = getenv('FROTA_SECRET_KEY');
$hmacKey     = hash_hmac('sha256', $accessToken, $secretKey);

$headers = [
    'Authorization: Basic ' . $accessToken,
    'Key: ' . $hmacKey,
    'cache-control: no-cache',
];

Python

import hmac
import hashlib
import os

access_token = os.environ['FROTA_ACCESS_TOKEN']
secret_key   = os.environ['FROTA_SECRET_KEY'].encode()

hmac_key = hmac.new(secret_key, access_token.encode(), hashlib.sha256).hexdigest()

headers = {
    'Authorization': f'Basic {access_token}',
    'Key': hmac_key,
    'cache-control': 'no-cache',
}

cURL

ACCESS_TOKEN="meu_token_aqui"
SECRET_KEY="minha_chave_secreta"

# Calcular assinatura
HMAC_KEY=$(echo -n "$ACCESS_TOKEN" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')

# Fazer a chamada
curl -X GET \
  'https://apidev.v1.frota162.com.br/key/cars?pagination[page]=1&pagination[perpage]=10' \
  -H "Authorization: Basic $ACCESS_TOKEN" \
  -H "Key: $HMAC_KEY" \
  -H 'cache-control: no-cache'

---

Erros de autenticação

API v1 (formato fbk_xxx)

Código	Mensagem	O que aconteceu
fbk_001	Não autorizado	Token não encontrado, inválido ou assinatura HMAC incorreta
fbk_002	Sem permissão	A conta não tem permissão para acessar a empresa

{
  "message": "Não autorizado",
  "error": true,
  "code": "fbk_001"
}

Para a lista completa de códigos, consulte Tratamento de Erros.

Boas práticas

Lidar com rate limiting

Se a API retornar status 429 (muitas requisições), espere o tempo indicado no header Retry-After antes de tentar novamente:

async function fetchWithRetry(url: string): Promise<Response> {
  const response = await fetch(url, {
    headers: {
      Authorization: `Basic ${credentials}`,
      Key: hmacSignature,
    },
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.log(`Rate limited. Aguardando ${retryAfter}s...`);
    await sleep(retryAfter * 1000);
    return fetchWithRetry(url);
  }

  return response;
}

Checklist de segurança

• Credenciais sempre em variáveis de ambiente, nunca no código
• Todas as chamadas via HTTPS
• SECRET_KEY nunca exposta no frontend ou em logs
• Em caso de comprometimento, gere novas credenciais imediatamente no painel

---

Login automático (POST /key/generator)

Quando usar

Esta rota não gera credenciais de API. Ela cria um token de sessão temporário que permite autenticar um usuário no sistema Frota162 sem que ele precise digitar email e senha.

Cenários de uso:

• Iframe — embutir o sistema Frota162 dentro de outro sistema
• SSO simplificado — redirecionar o usuário para o Frota162 já autenticado após login no sistema parceiro
• Deep link autenticado — abrir uma tela específica do Frota162 sem exigir novo login

Como funciona:

1. Seu backend faz um POST /key/generator com as credenciais HMAC normais
2. A API retorna um token de sessão temporário (accessKey)
3. Você redireciona o usuário (ou carrega o iframe) usando a URL:

   https://app.frota162.com.br/login?accessKey={TOKEN_GERADO}

4. O Frota162 autentica o usuário automaticamente

Requisição:

curl -X POST \
  https://apidev.v1.frota162.com.br/key/generator \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{"email": "usuario@empresa.com", "password": "senha_do_usuario"}'

Resposta:

{
  "accessKey": "7a12ad20-136f-4c06-9f40-532a6e952127",
  "error": false,
  "code": "fbk_200"
}

Atenção

O accessKey retornado é de uso único e expira após o login. Não confunda com o ACCESS_TOKEN usado para autenticar chamadas da API.