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

# Listar menús

> Lee definiciones de menús compuestos para mapeo con POS o RMS.

Devuelve menús compuestos del comercio autenticado. Pasa parámetros de scope en query para acotar el contexto de venta. Cada menú compuesto se identifica por `fulfillment_id + store_id + channel_id + brand_id + menu.id` — las mismas dimensiones que [Upsert menus](https://firespark.cloud/docs/es/integrations-api/menus/put.md).

Este endpoint no filtra por horario. Devuelve todos los menús `ACTIVE` que coinciden con el scope resuelto, sin importar la hora actual. Usa [Get menu](https://firespark.cloud/docs/es/storefront-api/menus/get.md) cuando necesites el menú orientado al cliente según la hora del pedido.

> [!NOTE]
>
> Requiere un access token con el scope `menus:read`. Consulta
> [Token](https://firespark.cloud/docs/es/integrations-api/oauth/token/post.md) para obtener un token.

## Parámetros de consulta

| Parámetro | Requerido | Descripción |
| - | - | - |
| `fulfillment_id` | No | Identificador externo de fulfillment. Si se envía, devuelve menús solo de ese tipo. Omite para incluir todos los tipos de fulfillment dentro del scope de tienda y canal resuelto. Ver [List fulfillment](https://firespark.cloud/docs/es/integrations-api/fulfillment/get.md). |
| `store_id` | No | Identificador externo de tienda. Devuelve menús acotados a esa tienda. Omite o pasa `__ANY__` para el default del comercio. |
| `channel_id` | No | Identificador externo de canal. Devuelve menús acotados a ese canal. Omite o pasa `__ANY__` para todos los canales. |
| `brand_id` | No | Identificador externo de marca. Omite o pasa `__ANY__` para el default del comercio. Si se envía, devuelve menús acotados a esa marca. |
| `menu_id` | No | Identificador externo de menú. Si se envía, devuelve un menú compuesto. Omite para devolver todos los menús que coincidan con los otros parámetros — por ejemplo horarios de almuerzo y cena en la misma tienda y canal. |

Omitir `fulfillment_id`, `store_id`, `channel_id` o `brand_id` no devuelve menús de todas las tiendas, canales o marcas. Cada uno resuelve al scope wildcard guardado como `__ANY__`, igual que [Upsert menus](https://firespark.cloud/docs/es/integrations-api/menus/put.md). Usa `menu_id` para acotar más dentro de ese scope.

## Request

```bash theme={null}
curl "https://firespark.cloud/api/integrations/v1/menus?fulfillment_id=delivery&store_id=centro&channel_id=app&brand_id=0001&menu_id=almuerzo-delivery" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Response

La respuesta envuelve un arreglo de objetos menú en `data`. Cada menú está acotado a una combinación de tienda, canal y fulfillment e incluye la estructura del catálogo compuesto y el horario semanal. Se devuelven todos los menús que coinciden, incluso los que están fuera de su ventana horaria activa.

```json Success theme={null}
{
  "data": [
    {
      "id": "almuerzo-delivery",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "store_id": "centro",
      "store_uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "channel_id": "app",
      "channel_uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "fulfillment_id": "delivery",
      "fulfillment_uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "name": { "en_us": "Menú almuerzo delivery" },
      "description": { "en_us": "Ítems de almuerzo entre semana para delivery en app" },
      "schedules": [
        {
          "day_of_week": "monday",
          "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }]
        },
        {
          "day_of_week": "tuesday",
          "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }]
        },
        {
          "day_of_week": "wednesday",
          "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }]
        },
        {
          "day_of_week": "thursday",
          "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }]
        },
        {
          "day_of_week": "friday",
          "periods": [{ "start_time": "11:00:00", "end_time": "15:00:00" }]
        }
      ],
      "products": [
        {
          "id": "hamburguesa-clasica",
          "name": { "en_us": "Hamburguesa clásica" },
          "description": { "en_us": "Carne Angus con lechuga y tomate." },
          "image_url": "https://cdn.example.com/hamburguesa-clasica.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 1,
            "maximum_quantity": 10,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 12.99,
            "anchor_price": 14.99,
            "anchor_price_percentage": 0.13,
            "modifiers": [],
            "modifier_group_ids": ["elige-bebida"]
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "refresco",
          "name": { "en_us": "Refresco" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        },
        {
          "id": "cola",
          "name": { "en_us": "Cola" },
          "description": null,
          "image_url": null,
          "cms_template_id": null,
          "status": "ACTIVE",
          "bundled_items": [],
          "pricing": {
            "minimum_quantity": 0,
            "maximum_quantity": 1,
            "is_tax_inclusive": true,
            "tax_rate": 0.15,
            "price": 0,
            "anchor_price": 0,
            "anchor_price_percentage": 0,
            "modifiers": [],
            "modifier_group_ids": []
          },
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "categories": [
        {
          "id": "principales",
          "name": { "en_us": "Platos fuertes" },
          "description": { "en_us": "Hamburguesas y sándwiches" },
          "image_url": "https://cdn.example.com/mains.jpg",
          "cms_template_id": null,
          "status": "ACTIVE",
          "items": [{ "type": "PRODUCT", "id": "e5f6a7b8-c9d0-1234-ef56-789012345678" }],
          "availability": {
            "status": "AVAILABLE",
            "schedules": null,
            "out_of_stock_until": null
          },
          "metadata": {}
        }
      ],
      "modifier_groups": [
        {
          "id": "elige-bebida",
          "title": { "en_us": "Elige una bebida" },
          "description": null,
          "display_type": "LIST",
          "modifier_ids": ["cola", "refresco"],
          "minimum_quantity": 0,
          "maximum_quantity": 1,
          "charge_above_quantity": null,
          "metadata": {}
        }
      ],
      "metadata": {},
      "cms_template_id": null,
      "cms": null,
      "status": "ACTIVE",
      "release": "v2026-07-10-21h"
    }
  ]
}
```

## Objeto menú

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | Identificador externo del menú. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Único por scope (`fulfillment_id`, `store_id`, `channel_id`, `brand_id`). |
| `uid` | string (UUID) | Identificador interno de Fire spark. |
| `merchant_id` | string (UUID) | Comercio al que pertenece el menú. |
| `store_id` | string | Identificador externo de la tienda a la que aplica este menú. |
| `store_uid` | string (UUID) | Identificador de tienda en Fire spark. |
| `channel_id` | string | Identificador externo del canal al que aplica este menú. |
| `channel_uid` | string (UUID) | Identificador de canal en Fire spark. |
| `fulfillment_id` | string | Identificador externo de fulfillment al que aplica este menú. |
| `fulfillment_uid` | string (UUID) | Identificador de fulfillment en Fire spark. |
| `name` | object | Nombre visible localizado por locale (por ejemplo `en_us`). Cada valor tiene 1–1024 caracteres. |
| `description` | object \| null | Descripción localizada por locale. `null` si se omite. Cada valor tiene 1–1024 caracteres. |
| `schedules` | array \| null | Entradas de horario semanal. `null` cuando no hay restricción de horarios. |
| `products` | array | Productos en este menú compuesto. Consulta el acordeón **products**. |
| `categories` | array | Categorías en este menú compuesto. Consulta el acordeón **categories**. |
| `modifier_groups` | array | Grupos de modificadores en este menú compuesto. Consulta el acordeón **modifier\_groups**. |
| `variant_groups` | array | Grupos de variantes en este menú compuesto. Consulta el acordeón **variant\_groups**. |
| `metadata` | object | Metadatos del partner. Por defecto `{}`. |
| `cms_template_id` | string (UUID) | Plantilla CMS vinculada a este menú. `null` si no hay plantilla asignada. |
| `cms` | object | Solo lectura. `null` cuando `cms_template_id` es `null`. Si está asignada, la plantilla CMS resuelta. |
| `status` | string | `ACTIVE` o `INACTIVE`. |
| `release` | string | Id del release que publicó este menú (desde `x-release-id` en el sync). |

> [accordion] schedules
>
> Arreglo de entradas de horario, o `null` cuando no hay restricción de horarios. Cuando está presente, el arreglo debe contener exactamente **7** entradas — una por día de `monday` a `sunday` — sin días duplicados ni periodos solapados en el mismo día.
>
> Cada entrada:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `day_of_week` | Sí | string | `monday` a `sunday`. |
> | `periods` | Sí | array | Una o más ventanas horarias en las que el menú está activo ese día. Como máximo 10 por día. |
>
> Cada periodo:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `closed` | No | boolean | `true` cuando este periodo está cerrado. Por defecto `false`. |
> | `start_time` | Condicional | string | Hora ISO (por ejemplo `11:00:00`). Requerido salvo que `closed` sea `true`. |
> | `end_time` | Condicional | string | Hora ISO (por ejemplo `15:00:00`). Requerido salvo que `closed` sea `true`. |
> | `start_date` | No | string \| null | Fecha y hora ISO 8601 con offset, o `null` para el fallback siempre activo. Definir junto con `end_date`. |
> | `end_date` | No | string \| null | Fecha y hora ISO 8601 con offset, o `null` para el fallback siempre activo. Definir junto con `start_date`. |

> [accordion] products
>
> Cada producto en un menú compuesto incluye campos de catálogo más precio y disponibilidad del contexto:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador externo del producto. |
> | `name` | Sí | object | Nombre visible localizado por locale (por ejemplo `en_us`). |
> | `description` | No | object \| null | Descripción localizada. `null` si se omite. |
> | `image_url` | No | string | URL de imagen del producto. `null` si se omite. |
> | `cms_template_id` | No | string (UUID) | Plantilla CMS vinculada. `null` si no hay plantilla. |
> | `status` | Sí | string | `ACTIVE` o `INACTIVE`. |
> | `bundled_items` | No | array | Ítems incluidos en un bundle o combo. Por defecto `[]`. |
> | `pricing` | Sí | object | Precio, impuestos, límites de cantidad y configuración de modificadores. Ver **pricing**. |
> | `availability` | Sí | object | Disponibilidad del producto. Ver campos abajo. |
> | `metadata` | No | object | Metadatos del partner. Por defecto `{}`. |
>
> Cada objeto `availability`:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `status` | Sí | string | `AVAILABLE`, `HIDDEN` u `OUT_OF_STOCK`. |
> | `schedules` | No | array \| null | Entradas de horario con `day_of_week` y `periods`. `null` cuando no hay restricción de horarios. |
> | `out_of_stock_until` | No | string | Fecha y hora ISO 8601 opcional cuando el producto vuelve a stock. |
>
> Cada entrada de `bundled_items`:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador externo del producto incluido. |
> | `refund_price` | Sí | number | Monto de reembolso si el cliente quita este ítem del bundle. ≥ 0. |
> | `included_quantity` | Sí | number | Unidades incluidas por defecto. ≥ 0. |
>
> ```json Ejemplo de producto theme={null}
> {
>   "id": "hamburguesa-clasica",
>   "name": { "en_us": "Hamburguesa clásica" },
>   "description": { "en_us": "Carne Angus con lechuga y tomate." },
>   "image_url": "https://cdn.example.com/hamburguesa-clasica.jpg",
>   "cms_template_id": null,
>   "status": "ACTIVE",
>   "bundled_items": [],
>   "pricing": {
>     "minimum_quantity": 1,
>     "maximum_quantity": 10,
>     "is_tax_inclusive": true,
>     "tax_rate": 0.15,
>     "price": 12.99,
>     "anchor_price": 14.99,
>     "anchor_price_percentage": 0.13,
>     "modifiers": [],
>     "modifier_group_ids": ["elige-bebida"]
>   },
>   "availability": {
>     "status": "AVAILABLE",
>     "schedules": null,
>     "out_of_stock_until": null
>   },
>   "metadata": {}
> }
> ```

> [accordion] categories
>
> Cada categoría en un menú compuesto:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador externo de la categoría. |
> | `name` | Sí | object | Nombre visible localizado por locale. |
> | `description` | No | object \| null | Descripción localizada. `null` si se omite. |
> | `image_url` | No | string | URL de imagen de la categoría. `null` si se omite. |
> | `cms_template_id` | No | string (UUID) | Plantilla CMS vinculada. `null` si no hay plantilla. |
> | `status` | Sí | string | `ACTIVE` o `INACTIVE`. |
> | `items` | No | array | Entradas ordenadas de la categoría. Por defecto `[]`. |
> | `availability` | Sí | object | Disponibilidad de la categoría. Ver campos abajo. |
> | `metadata` | No | object | Metadatos del partner. Por defecto `{}`. |
>
> Cada entrada en `items`:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `type` | Sí | string | `CATEGORY` o `PRODUCT`. |
> | `id` | Sí | string | Identificador externo de categoría o producto. |
>
> Cada objeto `availability`:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `status` | Sí | string | `AVAILABLE`, `HIDDEN` u `OUT_OF_STOCK`. |
> | `schedules` | No | array \| null | Entradas de horario con `day_of_week` y `periods`. `null` cuando no hay restricción de horarios. |
> | `out_of_stock_until` | No | string | Fecha y hora ISO 8601 opcional cuando el producto vuelve a stock. |
>
> ```json Ejemplo de categoría theme={null}
> {
>   "id": "principales",
>   "name": { "en_us": "Platos fuertes" },
>   "description": { "en_us": "Hamburguesas y sándwiches" },
>   "image_url": "https://cdn.example.com/mains.jpg",
>   "cms_template_id": null,
>   "status": "ACTIVE",
>   "items": [{ "type": "PRODUCT", "id": "e5f6a7b8-c9d0-1234-ef56-789012345678" }],
>   "availability": {
>     "status": "AVAILABLE",
>     "schedules": null,
>     "out_of_stock_until": null
>   },
>   "metadata": {}
> }
> ```

> [accordion] modifier\_groups
>
> Cada grupo de modificadores en un menú compuesto:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador externo del grupo de modificadores. Referenciado desde `pricing.modifier_group_ids`. |
> | `title` | Sí | object | Título localizado del grupo por locale. |
> | `description` | No | object \| null | Descripción localizada. `null` si se omite. |
> | `display_type` | No | string | `GRID` o `LIST`. |
> | `modifier_ids` | Sí | array | UUIDs de productos modificadores en este grupo. Al menos 2 entradas. |
> | `minimum_quantity` | Sí | number | Selecciones mínimas requeridas. ≥ 0. |
> | `maximum_quantity` | Sí | number | Selecciones máximas permitidas. 0–1,000,000. |
> | `charge_above_quantity` | No | number | Selecciones gratuitas antes de cobrar adicionales. Opcional. |
> | `metadata` | No | object | Metadatos del partner. Por defecto `{}`. |
>
> ```json Ejemplo de grupo de modificadores theme={null}
> {
>   "id": "elige-bebida",
>   "title": { "en_us": "Elige una bebida" },
>   "description": null,
>   "display_type": "LIST",
>   "modifier_ids": ["cola", "refresco"],
>   "minimum_quantity": 0,
>   "maximum_quantity": 1,
>   "charge_above_quantity": null,
>   "metadata": {}
> }
> ```

> [accordion] variant\_groups
>
> Cada grupo de variantes:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador externo del grupo de variantes. Referenciado desde `pricing.variant_group_ids`. |
> | `title` | Sí | object | Pregunta localizada por locale. |
> | `description` | No | object \| null | Descripción localizada. |
> | `display_type` | No | string | `GRID` o `LIST`. |
> | `variants` | Sí | array | Opciones del grupo. Entre 1 y 100. Mira los campos abajo. |
> | `metadata` | No | object | Metadatos del partner. Por defecto `{}`. |
>
> Cada entrada en `variants`:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `id` | Sí | string | Identificador de la opción, único entre todos los grupos de variantes. Referenciado desde `pricing.variants[].variant_group_option_ids`. |
> | `name` | Sí | object | Etiqueta localizada de la opción. |
> | `description` | No | object \| null | Descripción localizada. |
> | `image_url` | No | string \| null | URL de imagen de la opción, servida desde el almacenamiento de Firespark igual que las imágenes de productos. |
> | `product_ids` | Sí | array | Productos variante a los que puede llevar esta opción. Cada uno debe existir y listar esta opción en su `pricing.variants`. Entre 1 y 1000. |
> | `metadata` | No | object | Metadatos del partner. Por defecto `{}`. |
>
> ```json Example variant group theme={null}
> {
>   "id": "size",
>   "title": { "en_us": "Size" },
>   "description": null,
>   "display_type": "GRID",
>   "variants": [
>     { "id": "medium", "name": { "en_us": "Medium" }, "description": null, "image_url": null, "product_ids": ["pep-m-thin", "pep-m-thick"], "metadata": {} },
>     { "id": "large", "name": { "en_us": "Large" }, "description": null, "image_url": null, "product_ids": ["pep-l-thin", "pep-l-thick"], "metadata": {} }
>   ],
>   "metadata": {}
> }
> ```

> [accordion] pricing
>
> Precio de producto en un menú compuesto:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `minimum_quantity` | Sí | number | Unidades mínimas por pedido. ≥ 0. |
> | `maximum_quantity` | Sí | number | Unidades máximas por pedido. 0–1,000,000. |
> | `is_tax_inclusive` | Sí | boolean | Si `price` incluye impuestos. |
> | `tax_rate` | Sí | number | Tasa de impuesto como decimal (por ejemplo `0.15` para 15%). 0–1. |
> | `price` | Sí | number | Precio de lista. ≥ 0. |
> | `anchor_price` | Sí | number | Precio de referencia para tachado o comparación. ≥ 0. |
> | `anchor_price_percentage` | Sí | number | Descuento mostrado respecto a `anchor_price`. 0–1. |
> | `starting_price` | No | number \| null | Precio "Desde" de referencia. Se calcula durante el sync si la integración lo omite; `null` significa que nunca se muestra. ≥ 0. |
> | `modifiers` | No | array | Overrides de precio y selección por grupo. Por defecto `[]`. |
> | `modifier_group_ids` | No | array | Identificadores externos de grupos de modificadores del producto. Por defecto `[]`. |
> | `variant_group_ids` | No | array | Grupos de variantes que se preguntan en este producto base. Cada id debe existir en `variant_groups` y aparecer una vez. Un producto con grupos de variantes no puede tener `modifier_group_ids`. Por defecto `[]`. Mira [Variantes](https://firespark.cloud/docs/es/concepts/products.md#variantes-y-grupos-de-variantes). |
> | `variants` | No | array | Cuando este producto es una variante: una entrada por base, cada una `{ "product_id": id de la base, "variant_group_option_ids": [...] }` con exactamente una opción de cada grupo de la base. Por defecto `[]`. |
>
> Cada objeto en `modifiers` configura un grupo de modificadores referenciado en `modifier_group_ids`. Acepta los mismos campos de precio que el producto padre, más campos específicos del modificador:
>
> | Campo | Requerido | Tipo | Descripción |
> | - | - | - | - |
> | `modifier_group_id` | Sí | string | Identificador externo del grupo de modificadores. Debe coincidir con un grupo en `modifier_group_ids`. |
> | `minimum_quantity` | Sí | number | Unidades mínimas por pedido para modificadores de este grupo. ≥ 0. |
> | `maximum_quantity` | Sí | number | Unidades máximas por pedido para modificadores de este grupo. 0–1,000,000. |
> | `is_tax_inclusive` | Sí | boolean | Si `price` incluye impuestos para modificadores de este grupo. |
> | `tax_rate` | Sí | number | Tasa de impuesto como decimal (por ejemplo `0.15` para 15%). 0–1. |
> | `price` | Sí | number | Precio de lista para modificadores de este grupo. ≥ 0. |
> | `anchor_price` | Sí | number | Precio de referencia para tachado o comparación. ≥ 0. |
> | `anchor_price_percentage` | Sí | number | Descuento mostrado respecto a `anchor_price`. 0–1. |
> | `default_quantity` | Sí | number | Cantidad preseleccionada para modificadores de este grupo. ≥ 0. |
> | `charge_above_quantity` | No | number | Selecciones gratuitas antes de cobrar adicionales. Opcional. |
> | `display_type` | No | string | Cómo se muestran los modificadores en la UI: `RADIO`, `CHECKBOX` o `QUANTITY`. Opcional. |

## Límites de tasa

`GET` y `PUT /api/integrations/v1/menus` comparten un límite de **30 solicitudes por 10 segundos por comercio**, con clave en el `merchant_id` de tu access token. Envía **una solicitud a la vez** por comercio — espera la respuesta antes de iniciar la siguiente. Las respuestas incluyen `X-RateLimit-Limit` y `X-RateLimit-Reset`. En `429`, también lee `X-RateLimit-Remaining` y `Retry-After`. Ver [Upsert menús — Límites de tasa](https://firespark.cloud/docs/es/integrations-api/menus/put.md#límites-de-tasa).

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Parámetro de scope en query inválido. |
| `401` | Access token ausente o inválido. |
| `403` | El token no incluye el scope `menus:read`. |
| `429` | Límite de tasa excedido — espera `Retry-After` / `X-RateLimit-Reset` antes de reintentar. |


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