Gestionar Menus en Tiendas
La API de Rappi te permite administrar los menús de tus tiendas.
Puedes crear y actualizar menús en la plataforma, recuperar los elementos de los menús y revisar el estado de aprobación de tus solicitudes para crear o actualizar menús.
Las principales propiedades de los menús y los elementos creados a través de la API de Rappi consisten en los siguientes elementos:
storeId
: El identificador de la tiendaitems
: Los elementos del menúcategory
: La categoría de los elementos del menúid
: El SKU (Stock-Keeping Unit) que el aliado le otorga a esta categoríamaxQty
: La cantidad máxima de elementos que se pueden pedir en esta categoríaminQty
: La cantidad mínima de elementos que se pueden pedir en esta categoría (En toppings, si es 0 significa que no es obligatorio)name
: Nombre de la categoríasortingPosition
: Si es una categoría de producto, es la posición de la categoría en el menu. En caso de ser la categoría de un Topping, es la posición de la categoría dentro del producto
children
: Subelementos anidados en una categoríaname
: El nombre del elemento en el menúdescription
: La descripción del elemento en el menúimageUrl
: La url de la imagen del elemento en el menúprice
: El precio del artículo en el menúrappiIds
: El identificador que Rappi le da a este artículosku
: El SKU (Stock-Keeping Unit) que el aliado le otorga a este artículosortingPosition
: La posición del elemento en su categoríatype
: El tipo de artículomaxLimit
: Indicador máximo del artículo, es requerido solo si el tipo es toppingcombo
: Indica si el elemento pertenece a un combo.(si es true significa que pertenece a un combo)
Importante
En envíos de menus, se deben enviar los precios full en lugar de precios con descuento aplicado
Algunas de estas propiedades se subdividen en más objetos. Para obtener una vista detallada y una explicación más detallada de estos elementos, consulta el recurso de la API Menus en la Referencia de API .
Tipos de Mapeo
- Sin mapeo: El aliado carga su menu desde portal partners, sin colocar los SKUs de los items del menú. Al recibir una orden, el json de la orden tendrá los ids de rappi de los items pero sus SKUs serán null, por lo que el aliado es el que se encarga de descargar su menu y codificar sus SKUs.
- Self mapping: El aliado carga su menu desde portal partners y puede ingresar desde allí el SKU del ítem del menú. Esta información del SKU es tomado para obtener la asociación entre el SKU y el id de rappi del item, para enviarla como parte de la información de la orden al POS del aliado.
- Mapeo automático: El aliado debe enviar su menú consumiendo el endpoint POST menu, donde se deben recibir SKUs para cada item que se envie en el menú. El mapeo se genera por medio del envió del json del menú, generando una nueva versión de mapeo que queda disponible de tal manera que al generar una orden, el sistema toma la información registrada en la base de datos del mapeo automatico, y envía la información traducida de la orden al POS del aliado.
Mejoras con menu automatico
Replicaremos el orden de tus productos
en la app de Rappi como lo envías desde el POS.Conservaremos las configuraciones de promociones
cuando actualices los menus desde el POS.La validación del menu será inmediata
, evitando cualquier demora en la carga, y recibirás feedback en el momento (“aceptado“, “rechazado“ o con “error“).Conservaremos el historial de favoritos
de los clientes en la app de Rappi, ya que conservaremos el histórico de tus SKUs.
Crear un Menú para una Tienda
Utiliza el endpoint POST menu para crear menús a través de la API.
Si quieres que un grupo de tiendas compartan el menú, debes pedirle a Rappi que configure una como tienda padre
y al resto como tiendas hijas
. Una vez hecha esta configuración, solo se podrán enviar menús para tiendas padres
. Si se intenta enviar un menú a una tienda hija
el endpoint lo va a rechazar.
Para crear un menú:
Realiza una solicitud POST
a la siguiente URL y agrega un objeto JSON
al cuerpo de la solicitud con los siguientes objetos.
URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/menu
{COUNTRY_DOMAIN}
: Este es tu dominio de país de Rappi. Ver la lista de dominios de países.
Este es un ejemplo del objeto JSON
en el cuerpo de la solicitud:
{ "storeId": "900103361", "items": [ { "name": "Grilled Chicken Burger", "description": "Grilled chicken burger description", "price": 14000, "sku": "10", "sortingPosition": 0, "type": "PRODUCT", "category": { "id": "2090019638", "maxQty": 0, "minQty": 0, "name": "Burgers", "sortingPosition": 0 }, "children": [ { "category": { "id": "211", "maxQty": 1, "minQty": 0, "name": "Do you want to add?", "sortingPosition": 0 }, "name": "French Fries", "description": "crunchy french fries", "price": 5000, "sku": "1", "maxLimit": 1, "sortingPosition": 1, "type": "TOPPING" }, { "category": { "id": "211", "maxQty": 1, "minQty": 0, "name": "Do you want to add?", "sortingPosition": 0 }, "name": "Potato Wedges", "price": 7000, "sku": "2", "maxLimit": 1, "sortingPosition": 1, "type": "TOPPING" } ] }, { "name": "Hawaiian Pizza", "description": "hawaiian pizza description", "price": 18000, "sku": "11", "sortingPosition": 1, "type": "PRODUCT", "category": { "id": "2090019639", "maxQty": 0, "minQty": 0, "name": "Pizzas", "sortingPosition": 1 }, "children": [] } ] }
Note
Si necesitamos cambiar la disponibilidad de los products, podemos utilizar el módulo de Gestionar Disponibilidad
Note
Los valores de este JSON
no son datos reales. Asegúrate de reemplazarlos con tus datos cuando realices solicitudes de API. Puedes agregar más elementos al menú agregando más objetos en items
, separados por una coma.
El sistema muestra el mensaje de confirmación Menu updated and ready to be validated.
Note
No es posible procesar mas de 1 menú al tiempo, por tanto, si ya existe un menú en proceso de aprobación, todos los menus entrantes de la misma tienda serán ignorados
Tu menú está ahora bajo aprobación. Puedes consultar el estado de tu menú haciendo una solicitud GET
al endpoint menú
. Para obtener más información, Consulta la sección de Obtención de Información del Menú en esta página.
Validaciones sobre el menu recibido
Cuando Rappi recibe el menú, hace varias validaciones a tomar en cuenta.
-
Lista de Items vacía: Si se recibe una lista de items vacía, se retorna el error:
Items is required
. -
Items sin sku: El sku de los productos y los toppings no deben estar vacios ni ser nulos. Si no se cumple esta validacion, se retorna el error:
This Store needs skus in all items
. -
Nombres y descripciones validas: Para todos los items (productos o toppings) se valida que:
- La descripción de item debe tener un tamaño mínimo de 2 caracteres
- El nombre del item debe tener un tamaño mínimo de 2 caracteres
- El item debe contener una categoría
- El id de la categoría del Producto y de los Toppings no deben estar vacíos ni ser nulos
- El nombre de la categoría del Producto y de los Toppings deben tener un tamaño mínimo de 2 caracteres
El máximo de caracteres para los distintos campos son parámetros configurables que pueden cambiar en el tiempo.
Si no cumple alguna de estas validaciones, se retorna el error:
All items must have a valid name, category or product description.
.En caso de obtener un error por esta validación por favor contáctese con el funcionario de Rappi que está apoyando su proceso.
-
Tipos de items validos: Se valida que los items de primer nivel sean de tipo PRODUCT y los items dentro de la lista "children" sean de tipo TOPPING. Si esta validación falla se retorna el error
All parent items must be product type and children must be topping type.
-
Categorías de toppings duplicadas: Dentro de un producto, no pueden existir dos categorias de toppings con el mismo nombre y id pero distinto sortingPosition, si esta validación falla se retorna el error
The topping categories cannot be duplicated (same name and id but different sorting position)
-
Categorías de productos duplicadas: No pueden existir dos categorías de productos con el mismo nombre y distinto id o sortingPosition, si esta validación falla se retorna el error
The product categories cannot be duplicated (same name but different id or sorting position)
-
Límites de categorías de toppings: Para todos los toppings se valida:
- El maxQty de la categoría del topping no puede ser 0 ni mayor a 20
- El maxLimit del topping no puede ser 0 ni mayor al maxQty de su categoría
El error retornado es:
All toppings must have a valid maxQty or maxLimit must not be greater than maxQty
-
Producto con precio Cero: Para todos los productos se valida que:
- Un Producto sin toppings (children) tiene que tener precio mayor a 0
- Un Producto con toppings puede tener precio 0 si alguno de sus toppings tiene precio mayor a 0
El error retornado es:
Product price must be greater than 0 if the product doesn’t have any children. Otherwise at least one of its children must have price.
-
Sku Unico: No se aceptará que un mismo SKU sea enviado dos (2) veces con nombres, descripciones, precios o toppings distintos. Esta regla solo aplica para productos. No aplicarán para toppings categories, toppings o subitems. El mensaje de error retornado para esta validacion es:
Menu contains products with same sku, but they have different attributes (including topping categories and toppings)
Antes | Ahora |
---|---|
Aceptábamos que dos productos con variaciones utilicen el mismo SKU. Por ejemplo: Name: Hamburguesa Descripción: Hamburguesa SKU: ABC123 Toppings: - Extra >> Tomate Name: Hamburguesa Descripcion: Hamburguesa deliciosa SKU: ABC123 Toppings: - Extra >> Lechuga | Solo vamos a aceptar un SKU por producto (caso contrario deben ser SKUs diferentes). Por ejemplo: Name: Hamburguesa Descripcion: Hamburguesa SKU: ABC123 Toppings: - Extra >> Tomate >> Lechuga |
Note
En el proceso de gestion de menus, Rappi solo contempla 2 niveles de elementos: Productos y Toppings. No se permiten items dentro de un Topping.
- Formato de imagenes: Los formatos aceptados para imagenes son JPG, JPG200 y PNG. Deben ser de Maximo 1 MB
- Formato de url: Se valida que la url utilizada posea una estructura válida, también se válida que contenga http y https. El error retornado es:
Invalid urls were found
- Textos con Emojis: En caso de que alguno de los campos de texto posea un Emoji, se retorna el error:
Some text fields in the menu have emojis, please delete them.
.
Note
Menú automático no soporta la reutilización de skus (ids) cuando se desea crear nuevos productos topping categories, y toppings.
Obtención de Información del Menú
Una vez que Rappi aprueba el contenido del menú, puedes traer el contenido de los menús de tu tienda utilizando el endpoint GET menu
.
Para traer el contenido de los menús de tu tienda:
Realiza una solicitud GET
a la siguiente URL.
URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/menu
{COUNTRY_DOMAIN}
: Este es tu dominio de país de Rappi. Ver la lista de dominios de países.
El sistema devuelve una respuesta con un objeto JSON
con la información de los menús de la tienda.
Consultar el Estado de Aprobación de tus Menús
Después de crear un menú usando nuestra API, el equipo de Rappi valida la estructura y el contenido de tu menú.
Puedes utilizar el endpoint GET menu/approved/{storeId}
para consultar el estado de aprobación de tus menús.
Para consultar el estado de tus menús:
Realiza una solicitud GET
a la siguiente URL.
URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/menu/approved/{storeId}
{COUNTRY_DOMAIN}
: Este es tu dominio de país de Rappi. Ver la lista de dominios de países.
El sistema devuelve una respuesta con un objeto JSON
con el estado de aprobación de los menús de la tienda.
Note
Si el tiempo de espera para aprobación de un menú supera el SLA acordado, se debe contactar con el equipo de soporte para validar el estado del menú.
Recuperar tu Ultimo Menú Creado
Utiliza el endpoint GET menu/rappi/{storeId}
para recuperar la información del último menú creado para una tienda específica.
Para obtener el último menú creado:
Realiza una solicitud GET
a la siguiente URL:
URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/menu/rappi/{storeId}
-
{COUNTRY_DOMAIN}
: Este es tu dominio de país de Rappi. Ver la lista de dominios de países. -
{storeId}
: Este es el identificador de la integración de tu tienda.
El sistema devuelve una respuesta JSON
con la información del último menú creado para tu tienda.