Autenticação da API
O modelo de auth depende da família de endpoint que você chama:
- Endpoints
/api/v1/*(orders, cancel-order, cash-management, fiscal-callback, fiscal-print, channels-config, payment-methods-config) — só precisa dex-api-key: pk_live_.... Pule o fluxo de login abaixo. - Endpoints
/api/v4/integrations/sales/aggregator/*(legacy) — use o fluxo OAuth descrito nesta página para obter um Bearer access token.
O
x-api-key identifica sua integração. O token Bearer prova que sua sessão está autenticada. Você obtém o token chamando o endpoint de login.
Passo 1 — Obtenha um access token
ChamePOST /auth/login com sua API key no header e suas credenciais no body:
Passo 2 — Use o token em cada requisição
Inclua ambos os headers em todas as chamadas subsequentes à API:Os tokens expiram após
expiresIn segundos. Re-autentique antes da expiração para evitar erros 401 em requisições em andamento.Onde obter suas credenciais
As API keys e credenciais de conta são gerenciadas pelo dashboard do Fire em Developers → API Management; veja API keys. Entre em contato com a equipe da sua conta no Fire se não tiver acesso.Verificação de assinatura de webhook
Cada evento que o Fire envia é assinado para que seu sistema possa confirmar que realmente veio do Fire e não foi adulterado em trânsito.Como funciona
Quando você registra seu endpoint no dashboard do Fire, o Fire gera um secret de webhook — uma string aleatória que apenas você e o Fire conhecem. Ele nunca trafega em nenhuma requisição. Cada vez que o Fire envia um evento, usa esse secret para calcular uma assinatura do corpo da requisição e a anexa como headerX-Fire-Signature, junto com um header X-Fire-Timestamp. Seu sistema faz o mesmo cálculo sobre o body recebido e compara o resultado:
O header que leva a assinatura é
X-Fire-Signature por padrão, mas é configurável
por integração — se o dashboard mostrar um nome diferente para sua integração, use
esse.Configuração
Ao adicionar um endpoint de webhook em uma integração de agregadores, o painel exibe o signing secret desse endpoint (muitas vezes apenas uma vez). Copie e guarde com segurança — você precisa dele para verificar cada entrega.Passos de verificação
1
Leia o header de assinatura
Extraia o valor do header
X-Fire-Signature da requisição recebida. Tem a forma
sha256=<hex digest> — é um prefixo, não um hex puro.2
Recalcule a assinatura
Usando seu secret de webhook, calcule HMAC-SHA256 do body bruto da requisição (antes de qualquer parse de JSON), e adicione
sha256= antes do hex resultante.3
Compare
Compare o valor calculado (com o prefixo
sha256=) com o valor completo do header usando uma comparação de tempo constante. Se coincidirem, processe o evento. Se não, retorne 400 e descarte.Use os bytes brutos do body para o cálculo HMAC — não uma versão parseada ou re-serializada do JSON. Parsear e re-serializar pode alterar espaços ou a ordem das chaves e fazer com que assinaturas válidas falhem na verificação.
Proteção contra replay
Cada entrega também traz um headerX-Fire-Timestamp (Unix seconds — momento em que o
Fire assinou a requisição). O Fire não impõe hoje uma janela de tolerância do lado
servidor: se você quiser proteção contra uma requisição capturada e reenviada depois,
valide que o timestamp está dentro de uma tolerância que você escolher (ex.: 5
minutos) antes de aceitar o evento.