fulfillment_id + store_id + channel_id + brand_id + menu.id — las mismas dimensiones que Upsert menus.
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 cuando necesites el menú orientado al cliente según la hora del pedido.
Requiere un access token con el scope
menus:read. Consulta
Token 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. |
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. |
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. Usa menu_id para acotar más dentro de ese scope.
Request
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ú endata. 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.
{
"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). |
schedules
schedules
Arreglo de entradas de horario, o
Cada periodo:
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. |
| 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. |
products
products
Cada producto en un menú compuesto incluye campos de catálogo más precio y disponibilidad del contexto:
Cada objeto
Cada entrada de
| 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 {}. |
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. |
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. |
Ejemplo de producto
{
"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": {}
}
categories
categories
Cada categoría en un menú compuesto:
Cada entrada en
Cada objeto
| 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 {}. |
items:| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
type | Sí | string | CATEGORY o PRODUCT. |
id | Sí | string | Identificador externo de categoría o producto. |
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. |
Ejemplo de categoría
{
"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
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 {}. |
Ejemplo de grupo de modificadores
{
"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": {}
}
variant_groups
variant_groups
Cada grupo de variantes:
Cada entrada en
| 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 {}. |
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 {}. |
Example variant group
{
"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": {}
}
pricing
pricing
Precio de producto en un menú compuesto:
Cada objeto en
| 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. |
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 []. |
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.
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. |