> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Crea una API key de Fire, vincúlala a un vendor y elige los scopes que requiere cada endpoint.

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](https://docs.fire.rest/es/authentication.md).

## 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:

**1. 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](#vendor-scope).

**2. 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.

**3. Elige los scopes**

Selecciona al menos un scope. Otorga solo lo que tu integración llama — ver [Scopes](#scopes).

**4. 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:

```http theme={null}
x-api-key: <your_api_key>
```

> [!NOTE]
>
> `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`.

> [!NOTE]
>
> 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:

```json 403 — key not vendor-scoped theme={null}
{
  "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.

> [!NOTE]
>
> 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](https://docs.fire.rest/es/api-reference/update-order.md), [Confirmar pago](https://docs.fire.rest/es/api-reference/confirm-payment.md), [Ventas perdidas](https://docs.fire.rest/es/api-reference/lost-sales.md) |
| Orders Read | `orders:read` | [Listar órdenes](https://docs.fire.rest/es/api-reference/list-orders.md), [Listar órdenes de tienda](https://docs.fire.rest/es/api-reference/list-store-orders.md), [Obtener orden](https://docs.fire.rest/es/api-reference/get-order.md), [Elegibilidad de cancelación](https://docs.fire.rest/es/api-reference/cancellation-eligibility.md), [Impresión fiscal](https://docs.fire.rest/es/api-reference/fiscal-print.md), [Motivos de rechazo de pago](https://docs.fire.rest/es/api-reference/payment-decline-reasons.md) |
| Printing Read | `printing:read` | [Imprimir cierre del día](https://docs.fire.rest/es/api-reference/print-day-close.md), [Imprimir documento de orden](https://docs.fire.rest/es/api-reference/print-order-document.md) |
| Store Read | `store:read` | [Listar tiendas](https://docs.fire.rest/es/api-reference/list-stores.md), [Obtener tienda](https://docs.fire.rest/es/api-reference/get-store.md), [Listar terminales de tienda](https://docs.fire.rest/es/api-reference/list-store-terminals.md) — exigen una key **vendor-scoped** |
| Menu Read | `menu:read` | [Listar menús](https://docs.fire.rest/es/api-reference/list-menus.md), [Obtener menú](https://docs.fire.rest/es/api-reference/get-menu.md) |
| Cash Management Read | `cash-management:read` | [Efectivo esperado](https://docs.fire.rest/es/api-reference/cash-expected.md), [Conciliaciones de caja](https://docs.fire.rest/es/api-reference/cash-reconciliations.md) (lectura) |
| Cash Management Write | `cash-management:write` | [Conciliaciones de caja](https://docs.fire.rest/es/api-reference/cash-reconciliations.md), [Conciliaciones de caja (v2)](https://docs.fire.rest/es/api-reference/cash-reconciliations-v2.md) |
| Webhooks Fiscal Callback | `webhooks:fiscal` | [Callback fiscal](https://docs.fire.rest/es/api-reference/fiscal-callback.md) — el callback exige una key **vendor-scoped** |
| Webhooks KDS Order Status | `webhooks:kds` | [Estado de orden KDS](https://docs.fire.rest/es/api-reference/kds-order-status.md) — exige una key **vendor-scoped** |
| Webhooks Aggregator Order Status | `webhooks:aggregator` | [Estado de orden de agregador](https://docs.fire.rest/es/api-reference/aggregator-order-status.md) |
| Webhooks PlugNotas | `webhooks:plugnotas` | Callback del proveedor fiscal brasileño. |
| Channels Read | `channels:read` | [Configuración de canales](https://docs.fire.rest/es/api-reference/channels-config.md) |
| Payment Methods Read | `payment-methods:read` | [Configuración de métodos de pago](https://docs.fire.rest/es/api-reference/payment-methods-config-v2.md) |
| Kiosks Write | `kiosks:write` | Abrir y cerrar sesiones de arranque de kioscos. |
| Component Health | `component-health:write` | [Salud de componentes](https://docs.fire.rest/es/api-reference/component-health.md) |
| Fiscal Gateway (numbering) | `fiscal:write` | [Numeración de documentos fiscales](https://docs.fire.rest/es/api-reference/fiscal-documents-v2.md) |
| Document Types | `document-types:read` | [Tipos de documento fiscal](https://docs.fire.rest/es/api-reference/fiscal-document-types.md) |

> [!NOTE]
>
> 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.