API keys

Toda llamada a los endpoints /api/v1/* se autentica con una API key enviada en el header x-api-key. Esta página explica cómo crearla, qué significa vendor scope (la razón detrás de la mayoría de los 403) y qué scope necesita cada endpoint. Para el flujo de login, los demás headers y la verificación de firma de webhooks, consulta Autenticación.

Crear una key

Las keys se crean en el dashboard de Fire, en Developers → API Management (/developers/firepos-api-management). La página lista tus keys existentes (nombre, vendor, prefijo, scopes, estado, fecha de creación y de expiración). Antes de empezar, elige la cuenta y el vendor que quieres en el selector del dashboard (arriba), luego selecciona Create API Key y completa el formulario:

Revisa la cuenta y el vendor

El formulario muestra la Account y el Vendor a los que quedará vinculada la key. Salen de tu selección en el dashboard y no se cambian en el formulario. Con All vendors seleccionado, la key queda sin vínculo de vendor — ver Vendor scope.

Nombre y descripción

Name es obligatorio (por ejemplo, XMART Production). Description es opcional: escribe para qué se usa la key, así podrás distinguirlas después.

Elige los scopes

Selecciona al menos un scope. Otorga solo lo que tu integración llama — ver Scopes.

Define una expiración (opcional)

Elige una fecha, o déjala vacía para una key que nunca expira.

Selecciona Create API Key, copia la key (empieza con pk_live_) y guárdala de forma segura. Envíala en cada petición:

x-api-key: <your_api_key>

x-api-key es el header recomendado. Fire también acepta la misma key como Authorization: Bearer pk_live_... (alias legacy, que la pantalla del dashboard todavía menciona). Si envías ambos, se usa x-api-key.

Contacta a tu equipo de cuenta de Fire si no ves API Management bajo Developers en tu dashboard.

Administrar keys

Editar scopes: puedes cambiar los scopes de una key sin cambiar su secreto.
Nombre, descripción y expiración no se pueden editar después de crear la key.
Revocar: una key revocada deja de funcionar y no se puede volver a editar.
Rotación: no hay rotación integrada. Para rotar, crea una key nueva con los mismos scopes, cambia tu integración a la nueva y luego revoca la anterior.

Vendor scope

Una key vendor-scoped está vinculada a una cuenta y a un vendor (una marca o concepto dentro de esa cuenta). Fire deriva ambos de la propia key — nunca envías accountId ni vendorId como parámetros — y solo devuelve o acepta datos que pertenecen a ese vínculo. La mayoría de los endpoints /api/v1/fire/external/* y los webhooks de entrada (webhooks:*) exigen una key vendor-scoped. Una key sin vendor se rechaza:

403 — key not vendor-scoped

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key must be vendor-scoped (account + vendor binding) to access this endpoint"
}

Para obtener una key vendor-scoped, selecciona un vendor en el dashboard antes de crearla. Los datos de otra cuenta o de otro vendor también devuelven 403, así que lo más limpio es una key por vendor.

Scopes

Un scope da acceso a una familia de endpoints. Una key sin el scope requerido se rechaza con 403 y un mensaje que indica el scope que falta.

Junto a algunos scopes el dashboard muestra requires account o requires vendor. Esa etiqueta solo se valida al guardar la key. Cada endpoint exige su propio vínculo cuando lo llamas, y no siempre coincide con la etiqueta — la página del endpoint indica lo que necesita. Ante la duda, crea la key con un vendor seleccionado.

Etiqueta del dashboard	Scope	Endpoints
Orders Write	`orders:write`	Actualizar orden, Confirmar pago, Ventas perdidas
Orders Read	`orders:read`	Listar órdenes, Listar órdenes de tienda, Obtener orden, Elegibilidad de cancelación, Impresión fiscal, Motivos de rechazo de pago
Printing Read	`printing:read`	Imprimir cierre del día, Imprimir documento de orden
Store Read	`store:read`	Listar tiendas, Obtener tienda, Listar terminales de tienda — exigen una key vendor-scoped
Menu Read	`menu:read`	Listar menús, Obtener menú
Cash Management Read	`cash-management:read`	Efectivo esperado, Conciliaciones de caja (lectura)
Cash Management Write	`cash-management:write`	Conciliaciones de caja, Conciliaciones de caja (v2)
Webhooks Fiscal Callback	`webhooks:fiscal`	Callback fiscal — el callback exige una key vendor-scoped
Webhooks KDS Order Status	`webhooks:kds`	Estado de orden KDS — exige una key vendor-scoped
Webhooks Aggregator Order Status	`webhooks:aggregator`	Estado de orden de agregador
Webhooks PlugNotas	`webhooks:plugnotas`	Callback del proveedor fiscal brasileño.
Channels Read	`channels:read`	Configuración de canales
Payment Methods Read	`payment-methods:read`	Configuración de métodos de pago
Kiosks Write	`kiosks:write`	Abrir y cerrar sesiones de arranque de kioscos.
Component Health	`component-health:write`	Salud de componentes
Fiscal Gateway (numbering)	`fiscal:write`	Numeración de documentos fiscales
Document Types	`document-types:read`	Tipos de documento fiscal

Cada página de endpoint indica el scope exacto en su parámetro x-api-key. Si esta tabla y una página de endpoint discrepan, manda la página del endpoint.

Errores comunes

Estado	Causa	Solución
`401`	Falta `x-api-key` o es inválida	Envía la key en el header `x-api-key`.
`403` — scope faltante	La key no tiene el scope que exige el endpoint	Usa una key que incluya ese scope. Puedes agregar scopes a una key existente.
`403` — no vendor-scoped	La key no tiene vínculo de vendor	Crea una key nueva con un vendor seleccionado en el dashboard.

Primeros pasos

Configuración

Trabajando con eventos

Guías

Crear una key

Administrar keys

Vendor scope

Scopes

Errores comunes

​Crear una key

​Administrar keys

​Vendor scope

​Scopes

​Errores comunes

Crear una key

Administrar keys

Vendor scope

Scopes

Errores comunes