> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# El modelo de menú
> Cómo se estructura un menú de Maple, cómo asignar su propio catálogo a él y las reglas que evitan suposiciones erróneas.
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ú](/es/developer-api/guides/publish-menu) cubre el flujo de solicitudes, [Recetas de menú](/es/developer-api/guides/menu-recipes) ofrece ejemplos prácticos y la [referencia de endpoints](/es/developer-api/api-reference) 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](#disponibilidad-y-franjas-horarias).
Al publicar se reemplaza ese único menú completo (se aplica como una diferencia; vea [más abajo](#publicar-reemplaza-todo-el-menú)). 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.**
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:
```mermaid theme={null}
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. |
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:
```json theme={null}
{ "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](/es/developer-api/concepts/money).
## 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ú](/es/developer-api/guides/menu-recipes) para ver ejemplos prácticos.
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](/es/developer-api/guides/publish-menu).
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](/es/developer-api/guides/menu-recipes).
## 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ú](/es/developer-api/guides/publish-menu).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.