El modelo de menú

Un menú es la descripción estructurada de todo lo que un cliente puede pedir en un local: los artículos, cómo se les asigna el precio, cómo se personalizan y qué impuestos y cargos aplican. Usted lo publica como un solo documento JSON, y Maple identifica cada objeto por los ID externos que usted asigna. Esta página explica el modelo y cómo asignar su propio catálogo a él. La guía Publique un menú cubre el flujo de solicitudes, Recetas de menú ofrece ejemplos prácticos y la referencia de endpoints enumera todos los campos.

Un menú por local

Cada local tiene exactamente un menú. No existe el concepto de varios menús con nombre (un “menú de desayuno” y un “menú de cena” por separado) para un local: las diferencias por horario se expresan dentro del único menú mediante ventanas de disponibilidad.

Al publicar se reemplaza ese único menú completo (se aplica como una diferencia; vea más abajo). Maple guarda internamente el historial de versiones y siempre sirve la versión actual, pero desde su lado el modelo es simple: un local, un menú, que usted publica completo.

Note

Si su sistema modela varios menús por local, conviértalos en un solo menú de Maple antes de publicar, normalmente como categorías separadas con sus propias ventanas de disponibilidad.

El árbol

Un menú es un árbol de tres objetos anidados, con definiciones compartidas a las que se hace referencia desde dentro:

flowchart TD
  Cat[Category] --> Item[Item]
  Item --> Var[Variation · carries the price]
  Item -.modifierGroups.-> MG[Modifier group]
  Var -.modifierGroups.-> MG
  MG --> Opt[Modifier option]
  Opt -.nested.-> MG
  Item -.taxCategoryId / taxRateIds.-> Tax[Tax category & rates]
  Item -.feeIds.-> Fee[Fees]

• Categoría (Category): una sección del menú (Bebidas, Platos fuertes). Puede tener franjas horarias para que solo aparezca en ciertas ventanas.
• Artículo (Item): un producto. Tiene una o más variantes y puede llevar grupos de modificadores, impuestos y cargos.
• Variante (Variation): una forma comprable de un artículo (Chico / Grande, o simplemente “Regular”). El precio vive aquí. Todo artículo tiene al menos una.
• Grupo de modificadores (Modifier group): un conjunto de opciones (Leche, Ingredientes extra) con reglas de selección. Se define una vez y se comparte, o se define en línea dentro de un artículo. Las opciones pueden llevar a su vez grupos de modificadores anidados.

Asigne su propio catálogo

La mayoría de los integradores ya tiene un modelo de menú. Así se asignan los conceptos típicos; hacerlo bien desde el principio evita los errores más comunes:

Su concepto	Se asigna a	Notas
Sección o encabezado del menú	Categoría	El orden importa; las categorías pueden tener franjas horarias.
Producto / platillo	Artículo	Un nombre y una descripción; no es donde vive el precio.
Tamaño / opción que cambia el precio base (Chico/Grande)	Variante del artículo	No es un artículo aparte. Todo artículo necesita al menos 1 variante, aunque sea solo “Regular”.
Complemento / personalización (shot extra, sin cebolla)	Opción de modificador en un grupo de modificadores	El grupo lleva las reglas de selección; la opción lleva cualquier cambio de precio.
Un conjunto de opciones reutilizable en muchos artículos (Leche)	Grupo de modificadores compartido referenciado con groupId	Se define una vez y se referencia en todas partes.
Combo / armado a gusto con sub-opciones	Grupos de modificadores anidados	Las opciones pueden llevar sus propios grupos de modificadores.

Warning

Suposiciones erróneas comunes que debe evitar: el precio no vive en el artículo (vive en la variante); un tamaño no es un artículo aparte (es una variante); y hay un menú por local (las franjas horarias son ventanas de disponibilidad, no menús separados).

Los ID externos son suyos

Todo objeto (categoría, artículo, variante, grupo de modificadores, opción, tasa de impuesto, cargo) lleva un externalId que usted asigna y del que es dueño. Maple nunca lo cambia. Es la base del modelo:

• Volver a publicar con el mismo externalId actualiza el mismo objeto en lugar de crear un duplicado.
• Los artículos de los pedidos hacen referencia al menú mediante estos ID (menu_entity_id), de modo que un pedido entrante se asigna directamente a su catálogo.
• Maple también genera sus propios ID (item_…, var_…, ctg_…) en las respuestas como referencia, pero usted direcciona todo por su externalId.
• Los objetos también se referencian entre sí por externalId. Cuando una referencia a un grupo de modificadores usa groupId, un artículo apunta a una tasa de impuesto con taxRateIds, o una promoción nombra su descuento con discountId, esos valores son los externalId que usted asignó, no los ID generados por Maple.

Use ID estables en su propio sistema (un SKU, una clave primaria), no el nombre visible, que puede cambiar.

Precios

Los precios son objetos, no números sueltos, para que el modelo pueda expresar más que un monto fijo. La estructura base es un monto en unidades menores enteras con una moneda:

{ "amount": { "amountMinor": 450, "currency": "USD" } }

El objeto de precio también admite tipos de precio (fixed, variable de monto abierto, per_unit para artículos que se pesan, bulk por tramos de cantidad), precios con impuesto incluido, reemplazos por moneda y un monto de comparación (tachado). Para el caso común, un precio fijo en una sola moneda, solo necesita amount. Consulte Dinero y montos.

Modificadores

Un grupo de modificadores tiene reglas de selección y un conjunto de opciones. Las reglas son más completas que un simple mínimo/máximo, lo que permite expresar cosas como “elija hasta 3, pero no más de 2 iguales”:

Campo	Controla
minSelections / maxSelections	Total de selecciones permitidas (contando cantidades).
minUniqueSelections / maxUniqueSelections	Cuántas opciones distintas se pueden elegir.
freeSelectionCount	Cuántas selecciones son gratis antes de que se apliquen cargos.
allowedQuantities	Cantidades permitidas por opción.
minQuantity / maxQuantity de la opción	Límites de una sola opción.

Referencie un grupo compartido desde un artículo o una variante con groupId, o defina uno en línea. Las dos formas son mutuamente excluyentes en una misma entrada: una referencia lleva solo groupId; una definición lleva name y options. Mezclarlas se rechaza en lugar de truncarse en silencio. Las opciones pueden llevar sus propios grupos de modificadores anidados para flujos de armado a gusto. Consulte Recetas de menú para ver ejemplos prácticos.

Note

Por ahora, los recursos de pedido exponen los modificadores de primer nivel seleccionados directamente en cada artículo. Las selecciones anidadas más profundas todavía no se expanden en el recurso del pedido.

Impuestos y cargos

Son definiciones de nivel superior que usted asocia a los artículos por ID:

• Categorías y tasas de impuesto: las tasas pueden ser percentage, flat o por tramos (bracket), sobre una base configurable, con impuesto incluido o no. Se asocian con taxCategoryId / taxRateIds.
• Cargos (Fees): recargos y depósitos (un depósito por envase o CRV), que se asocian con feeIds.
• Descuentos, promociones y cupones: colecciones opcionales de nivel superior para reducciones de precio.

La mayoría de los menús necesita una sola tasa de impuesto y ningún cargo; las construcciones más completas están disponibles cuando un local las necesita.

Disponibilidad y franjas horarias

Las ventanas de disponibilidad son la forma de expresar menús por horario; esto reemplaza la idea de tener varios menús.

• Una categoría con una ventana de disponibilidad solo aparece durante ella (desayuno hasta las 11:00).
• Un artículo también puede llevar sus propias ventanas.
• Un objeto sin disponibilidad está siempre disponible.

Cada ventana es un día más un rango de horas locales:

• dayOfWeek: de 0 (domingo) a 6 (sábado). Agregue una ventana por cada día activo.
• startTime / endTime: hora local HH:MM, en formato de 24 horas.

Las ventanas se evalúan en la zona horaria del menú, definida por el campo de nivel superior timezone (IANA, por ejemplo America/New_York). Si no se define, el valor predeterminado es UTC, así que configúrelo en su primera publicación; consulte Defina la zona horaria para la disponibilidad.

Una “especialidad del día” o una sección de desayuno es una categoría (o un artículo) con las ventanas adecuadas, dentro del único menú. Consulte la receta de especialidades del día.

Estado de inventario

El estado de inventario es in_stock, out_of_stock o low_stock. Al publicar, omitirlo conserva el valor actual; los objetos nuevos quedan en in_stock de forma predeterminada. Úselo para marcar un artículo como agotado sin volver a publicar la estructura completa del menú.

Publicar reemplaza todo el menú

Siempre envía el menú completo como el estado deseado. Maple lo aplica como una diferencia basada en externalId:

• La validación es de todo o nada: un 400 enumera todos los problemas y no cambia nada.
• Volver a publicar algo idéntico no hace nada, y las identidades de los objetos se mantienen estables, así que puede publicar cada vez que cambie el menú sin generar alteraciones.

Por eso, la integración más simple vuelve a publicar el menú completo cada vez que cambia su fuente. Consulte Publique un menú.