Gestionar Ordenes de Usuario#

Referencia de API

La API de Rappi te permite administrar las órdenes que hacen los usuarios utilizando la aplicación de Rappi. Las siguientes secciones describen el proceso para:

  • Gestionar el flujo de trabajo y el estado de las órdenes de los usuarios.
  • Obtener órdenes de usuarios a través de solicitudes al API.

Propiedades del Pedido#

Las siguientes secciones describen las propiedades de las órdenes, sus diferentes estados y los eventos que ocurren en las órdenes.

Estado del Pedido#

Cuando un usuario crea una orden, la orden sigue un flujo específico desde el momento en que la aplicación comienza a procesarlo. El sistema activa algunos de estos cambios de estado automáticamente cada vez que la orden se actualiza en la aplicación de Rappi, y los demás deben actualizarse manualmente.

La siguiente tabla describe los diferentes estados por los que pasa la orden:

Estado del pedido Descripción Tipo de actualización Transiciones desde Transiciones a
CREATED Cuando un usuario crea una orden en la aplicación de Rappi Automático N/A READY
READY Cuando la aplicación procesa la orden Automático CREATED SENT
SENT Cuando la aplicación envía la orden al usuario Manual READY TAKEN

REJECTED

TIMEOUT
TAKEN Cuando la tienda acepta la orden Manual READY READY_FOR_PICKUP
REJECTED Cuando la tienda rechaza la orden Manual READY N/A
TIMEOUT Cuando ni la tienda ni Rappi, realiza alguna acción sobre la orden Automático READY N/A
READY_FOR_PICKUP Cuando la tienda haya preparado la orden Automático TAKEN N/A
WEBHOOK Cuando la orden se procesa por webhook Automático N/A READY

De forma predeterminada, el sistema cambia la orden de TAKEN a READY_FOR_PICKUP automáticamente.

Si el pedido se está procesando a través de webhook, su estado inicial será WEBHOOK.

Si intenta hacer la transición de un pedido a un estado ilegal (por ejemplo, rechazar un pedido ya tomado), terminará en la imposibilidad de iterar el pedido y devolverá un mensaje de transición no válido.

Puedes solicitar a Rappi que gestione esta transición manualmente, teniendo en cuenta lo siguiente:

  • Cuando se establece en Automático, Rappi cambia el estado del pedido en función del tiempo de cocinado de la tienda y los registros de retrasos en órdenes.

  • Cuando se establece en Manual, debes llamar al endpoint POST orders/{orderId}/ready-for-pickup cuando la orden esté lista.

Important

Rappi recomienda mantener esta transición configurada en Automático, para evitar cualquier impacto en el flujo de sus órdenes.

Eventos de Ordenes#

Durante el ciclo de vida de una orden, el sistema indica una serie de eventos y cada uno de estos eventos desencadena una acción diferente en la aplicación de Rappi.

Por ejemplo, el sistema activa un evento cuando se asigna un repartidor para recoger una orden en una tienda, y el evento cambia cuando el repartidor entrega este pedido al usuario.

La API de Rappi te permite traer el historial de eventos de las órdenes.

La siguiente tabla describe los eventos que pueden ocurrir durante el ciclo de vida de una orden:

Evento de Pedido Descripción del Evento Transiciona desde Transiciona a
taken_visible_order Ocurre cuando:
- El pedido se asigna a la tienda dentro de Rappi, inmediatamente después de una toma exitosa de una orden.
- El repartidor se asigna al pedido, en este caso, Rappi también proporciona el tiempo estimado para que el repartidor llegue a la tienda.
N/A ready_for_pick_up

replace_storekeeper
replace_storekeeper Ocurre cuando Rappi asigna a un nuevo repartidor la orden, en este caso, Rappi también proporciona la ETA que tardará el repartidor en llegar a la tienda. taken_visible_order ready_for_pick_up
ready_for_pick_up Ocurre cuando la tienda prepara la orden y está lista para ser recogida. taken_visible_order

replace_storekeeper
domiciliary_in_store
domiciliary_in_store Ocurre cuando el repartidor está en la tienda. ready_for_pick_up hand_to_domiciliary
hand_to_domiciliary Ocurre cuando la tienda entrega la orden al repartidor. domiciliary_in_store arrive
arrive Se produce cuando la orden llega al domicilio del usuario. domiciliary_in_store close_order
close_order Ocurre cuando el usuario recibe la orden. arrive N/A

Enventos de Cancelación#

Cuando ocurre una cancelación en la plataforma Rappi, el sistema genera un evento de cancelación dependiendo del escenario y las circunstancias de la cancelación.

La siguiente tabla contiene los eventos de cancelación existentes y su descripción:

Envento de Cancelación Ocurre cuando:
cancel_by_user El usuario cancela una orden.
canceled_with_charge El usuario cancela una orden y Rappi aplica una tarifa de cancelación al usuario.
cancel_without_charges El usuario cancela una orden sin cargo para el usuario.
cancel_by_support El servicio de atención al usuario de Rappi cancela la orden.
cancel_by_support_with_charge El servicio de atención al usuario de Rappi cancela la orden y Rappi aplica una tarifa de cancelación al usuario.
cancel_by_application_user El aliado cancela una orden mediante la aplicación Cliente.
canceled_from_cms El servicio de atención al usuario de Rappi cancela la orden a través de la herramienta interna de CMS.
canceled_by_fraud_automation Rappi cancela una orden debido a la detección de fraude.
canceled_store_closed Rappi cancela una orden que el usuario hizo a una tienda cerrada.
cancel_by_sk_with_charge El servicio de repartición cancela la orden y Rappi aplica una tarifa de cancelación al servicio de repartición.

Total de Ordenes y Descuentos#

Rappi te permite configurar campañas de descuento mediante la aplicación Rappi Growth. Puedes aplicar descuentos a productos individuales, tiendas, o puedes configurar campañas de descuentos especiales para un número limitado de usuarios que realizan órdenes.

Utiliza la API de Rappi para ver los descuentos aplicados a las órdenes, los descuentos totales y los precios totales.

La siguiente tabla describe la información de descuentos en las órdenes:

Indicador de Descuento Descripción
unit_price_without_discount El precio unitario base del artículo. Nota: La información sobre subelementos no existe en este campo. Para ver estos datos, revisa cada subelemento.
percentage_discount El porcentaje de descuento aplicado al precio base.
unit_price_with_discount El precio unitario final después de aplicar el descuento.

La siguiente tabla describe los indicadores para los totales de órdenes disponibles:

Indicador de Total Descripción
total_products_without_discount La suma de los precios sin descuentos de todos los artículos y subelementos del pedido
total_products_with_discount El porcentaje de descuento aplicado al precio base
total_other_discounts La suma de todos los descuentos aplicados al pedido que no son específicos de un producto
total_order El total del pedido con descuentos
total_to_pay El importe restante a pagar en efectivo por el usuario
charges Los cargos en la orden
shipping La tarifa de envío del pedido
service_fee La tarifa del servicio de pedido
other_totals Los totales adicionales del pedido
tip La propina a pagar al repartidor
total_rappi_pay La cantidad pagada con Rappi Pay
total_rappi_credits El monto pagado con Rappicréditos

Métodos de Entrega#

Rappi te permite configurar diferentes métodos de entrega para tus órdenes.

Esta tabla describe los métodos de entrega disponibles:

Método de Entrega Descripción
delivery Un repartidor Rappi entrega la orden
marketplace Un repartidor de la tienda entrega la orden
pickup El usuario recoge la orden en la tienda

Rappi siempre admite la opción de delivery para todas sus tiendas, y puede elegir habilitar los métodos de entrega marketplace y pickup.

Puede configurar estas opciones a nivel de tienda con su principal punto de contacto de Rappi.

Datos del Domicilio#

Dependiendo de los métodos de entrega de sus tiendas, las respuestas de la API contienen información específica.

La siguiente tabla representa la información común compartida entre los diferentes métodos de entrega.

Campo Descripción
city La ciudad de la dirección del pedido
neighborhood El barrio de la dirección del pedido
postal_code El código postal de la dirección del pedido
complement La información adicional de la dirección
complete_address La dirección completa del pedido

Campos de Marketplace por País#

Las tiendas que tienen habilitado el método de entrega marketplace reciben información adicional en sus respuestas API.

La siguiente tabla representa la información adicional para cada país.

Argentina Brazil Colombia Mexico Peru Other Countries
street_name street_shorcut complementary_street_without_meter street_name street_shorcut description
street_number street_name complete_main_street_number street_number street_name -
description street_number main_street_number_letter - street_number -
- federal_unit complementary_street_quadrant - - -
- - meter - - -
- - complementary_street_prefix - - -
- - complete_main_street - - -
- - main_street_type - - -
- - main_street_number_or_name - - -
- - complementary_street_letter - - -
- - main_street_prefix_letter - - -
- - main_street_prefix - - -
- - complete_complementary_street - - -
- - complementary_street_number - - -
- - complementary_street_prefix_letter - - -
- - main_street_quadrant - - -

Recuperar Nuevas Ordenes#

Referencia de API

Utiliza el endpoint GET orders para recuperar una lista de todas las órdenes que están en estado READY para realizar más acciones.

Important

Solo puedes recuperar nuevas órdenes una sola vez. Después de recuperar estas órdenes, el sistema cambia su estado de READY a SENT.

Para recuperar nuevas órdenes:

Realiza una solicitud GET a la siguiente URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders

{COUNTRY_DOMAIN}: Este es tu dominio de país de Rappi. Ver la lista de dominios de países.

Note

Para recuperar solo las órdenes de una tienda específica, agregue el parámetro storeId a su solicitud, de la siguiente forma https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders?storeId={storeId}.

El sistema recupera una respuesta JSON con todos los nuevas órdenes de sus tiendas. Consulte la estructura de respuesta JSON en la sección de endpoint orders de la Referencia de API.

Cuando recupere la lista de sus nuevas órdenes, puede tomar, o rechazar las órdenes.

Recuperar Nuevas Ordenes En Estado SENT#

Referencia de API

Utiliza el endpoint GET orders/status/sent para recuperar una lista de todas las órdenes que están en estado SENT.

Important

Solo se van a tener en cuenta las ordenes que su último estado sea SENT y que ese estado haya sido actualizado dentro del límite del tiempo (10 minutos hacia adelante).

Ejemplo:

Si la orden paso a estado SENT a las 14:00 del día 12/10/2021, y se utiliza este endpoint a las 14:07 el mismo día, el resultado traerá la orden, debido a que 14:07 - 10 minutos = 13:57 y la hora de cambio de estado fue a las 14:00 por lo que es mayor a 13:57.

Otro ejemplo, si la orden paso a estado SENT a las 14:00 del día 12/10/2021, pero se consulta el endpont a las 17:30, el resultado no traerá la orden porque 17:30 - 10 minutos = 17:20, y la hora de cambio de estado fue a las 14:00 que es menor a 17:20.

Para recuperar nuevas ordenes en estado SENT:

Realiza una solicitud GET a la siguiente URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/status/sent

{COUNTRY_DOMAIN}: Este es tu dominio de país de Rappi. Ver la lista de dominios de países.

Note

Para recuperar solo las órdenes de una tienda específica, agregue el parámetro storeId a su solicitud.

El sistema recupera una respuesta JSON con todos los nuevas órdenes de sus tiendas. Consulte la estructura de respuesta JSON en la sección de endpoint orders de la Referencia de API.

Cuando recupere la lista de sus nuevas órdenes, puede tomar, o rechazar las órdenes.

Tomar Ordenes#

Referencia de API

Utiliza el endpoint PUT orders/{orderId}/take/{cookingTime} para recibir órdenes que se encuentran en estado SENT.

Important

Cuando tomas una orden, el sistema cambia su estado a TAKEN y la tienda comienza su preparación.

Aunque es inusual, si obtiene un estado diferente a 200, use patrones de resiliencia como reintentar; utilícelo junto con el retroceso exponencial para disminuir multiplicativamente la tasa de la solicitud.

Para aceptar una orden, haz una solicitud PUT a la siguiente URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/take/

Note

Puedes modificar el tiempo de cocción predeterminado del pedido ingresando un nuevo tiempo de cocción al final del endpoint con el parámetro {cookingTime}: /orders/{orderId}/take/{cookingTime}.

El sistema regresa un objeto JSON con el mensaje de confirmación "Order successfully taken".

Tiempo de Cocción#

Funcionalidad que permite modificar el tiempo de cocción de una orden al ser tomada y/o aceptada en el POS

¿Cuales son los tiempos de cocción?

La orden tiene tres posibles tiempos de coocción los cuales se aplican en el orden que se mencionan

  • Tiempo de cocción predictivo
  • Tiempo de cocción en CMS (con máximos y mínimos)
  • Tiempo de cocción configurado en el core de la integración

¿Cómo funciona el tiempo de cocción?

El sistema hace un recorrido por cada uno de los tiempos de cocción en el orden mencionado para asignar el tiempo de cocción a la orden, y en caso que NO encuentre uno continúa con el siguiente hasta asignar el tiempo de cocción.

¿Se puede cambiar el tiempo de cocción?

Sí, Puede cambiar el tiempo de cocción por un valor contenido entre los valores del mínimo y máximo configurado en el core de la integración, y en caso que envie un valor que salga del rango configurado el sistema de manera automática toma el cambio en el mínimo o máximo configurado en el core de la integración.

Rechazar Ordenes#

Referencia de API

Utiliza el endpoint PUT orders/{orderId}/reject para rechazar órdenes que están en estado SENT cuando:

  • El pedido contiene artículos no válidos o no disponibles.
  • El pedido contiene artículos con un precio incorrecto.

Important

No utilices este endpoint para limitar el número de órdenes que procesa la tienda. Si rechazas varias órdenes para una tienda determinada en poco tiempo, Rappi deshabilita la tienda en la aplicación.

También puedes deshabilitar elementos del menú de la tienda al rechazar órdenes, proporcionando el items_sku o el items_id al cuerpo de la solicitud.

Note

Los elementos que deshabilites al rechazar una orden solo pueden ser habilitados nuevamente por Soporte de Rappi. Para ver otras formas de deshabilitar elementos, consulta la sección Gestionar Disponibilidad de este portal.

Para rechazar una orden, haz una solicitud PUT 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/orders/{orderId}/reject

Este es un ejemplo del objeto JSON en el cuerpo de la solicitud:

{
   "reason":"The order has invalid items"
}

Note

Para deshabilitar elementos del menú de la tienda, agregue los objetos "items_sku" o los objetos "items_ids" debajo de "reason" en el objeto JSON.

El sistema recupera una respuesta de objeto JSON con el mensaje de confirmación "Order successfully rejected".

Notificar que la Orden Está Lista para ser Recogida#

Referencia de API

Si tus tiendas tienen configuraciones de notificación manual, use el endpoint POST orders/{orderId}/ready-for-pickup para notificar a la aplicación de Rappi cuando una orden está lista para ser recogida.

Para notificar a Rappi cuando una orden está lista para ser recogida:

Realiza una solicitud POST a la siguiente URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/ready-for-pickup

El sistema devuelve una respuesta JSON con el mensaje de confirmación "Order successfully updated".

Recuperar Eventos de Ordenes#

Referencia de API

Puedes recuperar los eventos de tu pedido utilizando el endpoint GET orders/{orderId}/events.

Para recuperar los eventos de tu pedido:

Realiza una solicitud GET a la siguiente URL:

URL: https://{COUNTRY_DOMAIN}/api/v2/restaurants-integrations-public-api/orders/{orderId}/events

El sistema recupera una respuesta JSON con el registro de los eventos de tu pedido.