Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 05/03/2026

Introducción Gestión de pedidos

Nota:
La gestión de órdenes se realiza a través de API REST, con las que podrás realizar acciones en función del estado actual de la orden.

Los cambios en el estado de la orden, desde el momento de la creación hasta la finalización de la entrega, se notificarán a través de un webhook que contiene el resource y el user_id en su body.


El atributo resource devuelve el shipment_id que se utilizará para cualquier operación relacionada con la orden y el atributo user_id devuelve el ID de usuario de la sucursal que recibió la orden.

Con shipment_id puedes:

  • Obtener datos de la orden.
  • Aceptar órdenes.
  • Imprimir el recibo de la orden.
  • Cancelar la orden.

Ready to Cook

Importante:
Con el objetivo de mejorar el encuentro entre el pedido listo y el repartidor, se debe comenzar a preparar el pedido únicamente cuando este se encuentre en el estado ready_to_ship / ready_to_cook.

Desde Mercado Pago se calcula el momento ideal para enviar a cocinar el pedido, teniendo presente tanto el tiempo de preparación necesario en la cocina como la capacidad logística del momento.

Nota:
Para simplificar, solo se hablará de "estado" pero en la práctica el pedido está compuesto por un estado / subestado. Por ejemplo, el estado sería ready_to_ship y el subestado ready_to_cook.

Requerimientos

  • Mercado Pago notificará al agregador el evento "Ready to Cook".
  • El agregador deberá dejar de comenzar a preparar el pedido cuando el mismo se encuentre en el estado ready_to_ship / on_route_to_pickup.
  • El agregador deberá comenzar a soportar un nuevo estado ready_to_ship / ready_to_cook que será devuelto por Mercado Pago al consultar el endpoint /proximity-integration/v2/orders/{shipmentId}.
  • El agregador comenzará a preparar el pedido únicamente cuando el mismo tenga el estado ready_to_ship / ready_to_cook.

Estrategia de Rollout

Se prevé un rollout progresivo, prendiendo el feature solo en algunos locales, por lo que será necesario que ambas maneras de iniciar la preparación convivan durante un tiempo hasta garantizar el correcto funcionamiento del evento "Ready to Cook".


Importante:
Desde Mercado Pago no se garantiza que los eventos siempre vengan en el siguiente orden. Puede que primero el pedido se actualice al estado ready_to_ship / on_route_to_pickup pero luego pase al estado ready_to_ship / ready_to_cook o viceversa.

Diagrama del flujo de estado

En Mercado Pago Delivery existen dos tipos de logística. De esta forma, el flujo de estados puede variar según el tipo de logística que estará ligada al pedido. A continuación hay una descripción de esos dos flujos.



Modalidad logística Flex

Este tipo de logística se utiliza generalmente en restaurantes que cuentan con sus propios repartidores. Los repartidores deben tener acceso a la aplicación móvil de Mercado Envíos Flex para escanear el código QR para registrarse y realizar la entrega. Al escanear este código QR, se notificará a los compradores que el pedido está en camino.

Es posible utilizar el código QR presente en el PDF disponible en la API o generar el código QR en su integración. La información, que debe estar contenida en el código QR, se puede obtener a través de la API de Mercado Pago Delivery utilizando el endpoint de consulta, donde estos datos serán devueltos en el atributo extension.qr.

Importante:
Es importante que el código QR esté disponible en el ticket del pedido para que el flujo de entrega se pueda realizar correctamente.

A continuación se describe el estado de todas las notificaciones que llegarán al webhook de pedidos vinculados a este tipo de logística:

Estado Descripción
ready_to_ship/ready_to_print Estado inicial de un pedido. En este estado se debe realizar alguna acción (aceptar o cancelar) en un máximo de 5 minutos, de lo contrario la orden será cancelada por timeout.
ready_to_ship/printed Estado que indica que el pedido ha sido aceptado.
ready_to_ship/ready_to_cook Estado que indica que se debe comenzar a preparar el pedido. Este es el momento óptimo calculado por Mercado Pago para iniciar la preparación.
shipped/out_for_delivery Estado que indica que el pedido está en camino a su ubicación de destino. Este estado se genera luego de que el repartidor escanea el código QR del pedido.
shipped/delivery_failed Estado que indica que hubo un problema durante la entrega del pedido.
delivered La entrega se completó con éxito.
cancelled/cancelled_manually Estado que indica que se realizó una operación de cancelación en el pedido.
cancelled/time_expired El pedido se canceló debido al timeout. Se produce cuando no se han realizado operaciones en los primeros cinco minutos desde la creación de la orden.

Modalidad logística Dropoff

Este tipo de logística es utilizada por los restaurantes que han acordado que las empresas de logística, que están integradas con Mercado Pago, realicen la entrega de los pedidos. En este flujo, poco después de aceptar un pedido, se enviará una notificación de que un repartidor estará en camino para recibir el pedido.

Importante:
A diferencia del flujo Flex, en esta modalidad de Dropoff los pedidos no tendrán código QR, por lo que al consultar el pedido mediante la API de Mercado Pago Delivery, el atributo extension.qr estará vacío.

Con este tipo de logística es posible tener asignado un repartidor antes de que se haya aceptado el pedido. Al aceptar el pedido siguiendo el flujo normal, el status/substatus: ready_to_ship / printed se mostraría al realizar el primer GET. Pero en los casos en que se asigna un repartidor muy rápidamente (antes de aceptar el pedido) es posible tener el status/substatus: ready_to_ship / on_route_to_pickup en el primer GET.

Por lo tanto, la recomendación para este tipo de logística es aceptar pedidos observando únicamente el status (ready_to_ship). Incluso con el repartidor asignado, es necesario aceptar el pedido dentro de los 5 minutos de su creación, de lo contrario, será cancelado por timeout.

Recuerda: Independientemente del estado on_route_to_pickup, NO se debe comenzar a preparar el pedido hasta recibir la notificación del estado ready_to_cook. La preparación debe iniciarse únicamente cuando el pedido tenga el estado ready_to_ship / ready_to_cook.

A continuación se describe el estado de todas las notificaciones que llegarán al Webhook de pedidos vinculados a esta modalidad logística:

Estado Descripción
ready_to_ship/ready_to_print En este estado se debe realizar alguna acción (aceptar o cancelar) en un máximo de 5 minutos, de lo contrario la orden será cancelada por timeout.
ready_to_ship/printed Estado que indica que se ha aceptado un pedido.
ready_to_ship/ready_to_cook Estado que indica que se debe comenzar a preparar el pedido. Este es el momento óptimo calculado por Mercado Pago para iniciar la preparación. La preparación SOLO debe iniciarse al recibir este estado.
ready_to_ship/on_route_to_pickup Este estado indica que el repartidor se dirige al restaurante. NO se debe comenzar a preparar el pedido en este estado.
ready_to_ship/picking_up El estado indica que el repartidor ha llegado al restaurante y está recogiendo el pedido.
shipped/out_for_delivery Indica que el repartidor ya ha salido a entregar el pedido.
shipped/at_the_door Indica que el repartidor ha llegado al destino del pedido.
delivered La entrega fue exitosa.
not_delivered Hubo un problema y el repartidor no pudo completar la entrega.
cancelled/cancelled_manually Estado que indica que se realizó una operación de cancelación en el pedido.
cancelled/time_expired El pedido se canceló debido a un timeout. Se produce cuando no se han realizado operaciones en los primeros cinco minutos desde la creación de la orden.

Siguiente: Consulta de Pedidos.