Autenticación de la API
El modelo de auth depende de la familia de endpoint que llames:
- Endpoints
/api/v1/*(orders, cancel-order, cash-management, fiscal-callback, fiscal-print, channels-config, payment-methods-config) — solo necesitásx-api-key: pk_live_.... Saltea el flujo de login que sigue abajo. - Endpoints
/api/v4/integrations/sales/aggregator/*(legacy) — usá el flujo OAuth descripto en esta página para obtener un Bearer access token.
El
x-api-key identifica tu integración. El token Bearer prueba que tu sesión está autenticada. Obtienes el token llamando al endpoint de login.
Paso 1 — Obtén un access token
Llama aPOST /auth/login con tu API key en el header y tus credenciales en el body:
Paso 2 — Usa el token en cada petición
Incluye ambos headers en todas las llamadas posteriores a la API:Los tokens expiran tras
expiresIn segundos. Re-autentica antes de la expiración para evitar errores 401 en peticiones en curso.Dónde obtener tus credenciales
Las API keys y las credenciales de cuenta se gestionan desde el dashboard de Fire en Developers → API Management; ver API keys. Contacta a tu equipo de cuenta de Fire si no tienes acceso.Verificación de firma de webhook
Cada evento que Fire envía está firmado para que tu sistema pueda confirmar que realmente vino de Fire y no fue manipulado en tránsito.Cómo funciona
Cuando registras tu endpoint en el dashboard de Fire, Fire genera un secret de webhook — una cadena aleatoria que sólo tú y Fire conocen. Nunca viaja en ninguna petición. Cada vez que Fire envía un evento, usa ese secret para calcular una firma del cuerpo de la petición y la adjunta como headerX-Fire-Signature, junto con un header X-Fire-Timestamp. Tu sistema realiza el mismo cálculo sobre el body que recibe y compara el resultado:
El header que lleva la firma es
X-Fire-Signature por default, pero es
configurable por integración — si el dashboard muestra un nombre distinto para tu
integración, usa ese.Configuración
Al añadir un endpoint de webhook en una integración de agregadores, el panel muestra el signing secret de ese endpoint (a menudo solo una vez). Cópialo y guárdalo de forma segura — lo necesitas para verificar cada entrega.Pasos de verificación
1
Lee el header de firma
Extrae el valor del header
X-Fire-Signature de la petición entrante. Tiene la
forma sha256=<hex digest> — es un prefijo, no un hex plano.2
Recalcula la firma
Usando tu secret de webhook, calcula HMAC-SHA256 del body crudo de la petición (antes de cualquier parseo JSON), y antepón
sha256= al hex resultante.3
Compara
Compara el valor calculado (con el prefijo
sha256=) contra el valor completo del header usando una comparación de tiempo constante. Si coinciden, procesa el evento. Si no, devuelve 400 y descártalo.Usa los bytes crudos del body para el cálculo HMAC — no una versión parseada o re-serializada del JSON. Parsear y re-serializar puede alterar espacios o el orden de las claves y hacer que firmas válidas fallen la verificación.
Protección contra replay
Cada entrega también lleva un headerX-Fire-Timestamp (Unix seconds — momento en que
Fire firmó la petición). Fire no impone hoy una ventana de tolerancia del lado
servidor: si querés protección contra una petición capturada y reenviada después,
valida que el timestamp esté dentro de una tolerancia que elijas (p. ej. 5 minutos)
antes de aceptar el evento.