Casos de uso - Endpoints Explicados#

Hay mucho que puedes hacer con una integración de órdenes Partner Picking. Aquí hay una lista rápida a continuación

Usa los siguientes enlaces para saltar al tema:

• Descripción general del endpoint PUT

• A través del endpoint PUT puedes realizar las siguientes acciones

  • Completar una orden - MANDATORIO

  • Cumplimiento parcial de una orden- MANDATORIO

  • Modificar los artículos en la orden y completar la orden - MANDATORIO

  • Modificar el peso de un artículo y completar la orden - MANDATORIO

  • Cancelar una orden - MANDATORIO

  • Reemplazar un artículo agotado - MANDATORIO

  • Agregar un nuevo artículo a la orden

  • Actualizar el carrito para validar los cambios (opcional)

• Recuperar el historial de órdenes usando los endpoints GET

  • Recuperar los detalles de una sola orden

  • Recuperar los detalles de múltiples órdenes

Descripción general del endpoint PUT#

Ver las especificaciones de la API

El endpoint PUT en el UUID de la orden ({order_id}) se usa para completar, modificar y reemplazar artículos en las órdenes. Las órdenes creadas por los clientes se envían a tu webhook configurado con el estado RECEIVED. Tus dispositivos de recolección pueden integrar el endpoint PUT para procesar las órdenes.

A continuación, se muestran los estados disponibles a nivel de orden y artículo:

• Estado de la orden:

  • RECEIVED, enviado por nuestro servicio a tu webhook cuando se crea una orden

  • READY_FOR_PICKUP, el estado se envía a tu webhook como confirmación cuando la orden se completa mediante el endpoint PUT

  • DISPATCHED,

    • Para el flujo de Entrega de la Plataforma: nuestro servicio envía automáticamente el estado a tu webhook después de que el repartidor recoge la orden

    • Para el flujo de Entrega del Vendedor: el estado se envía a tu webhook como confirmación cuando la orden se completa mediante el endpoint PUT

  • CANCELLED, nuestro servicio envía el evento cuando el cliente o la logística cancelan una orden.

  • UPDATE_CART, el estado se utiliza para las modificaciones de artículos mediante el endpoint PUT. No se activa ningún evento de webhook. Debe utilizarse antes de los estados de cumplimiento de la orden, es decir, READY_FOR_PICKUP o DISPATCHED.

• Estado del artículo:

  • IN_CART, el recolector agrega el artículo al carrito

  • NOT_FOUND, el artículo no está disponible en la tienda

  • NOT_PROCESSED, estado inicial de un artículo cuando se recibe en tu webhook

  • REPLACED, el artículo se ha eliminado de la orden con un reemplazo.

  • ADDITION, nuevo artículo adicional agregado a la orden

Las Integraciones de Picking del Partner te permiten elegir los flujos de entrega preferidos:

• Entrega de la Plataforma: Los repartidores de la plataforma entregarán las órdenes al cliente. Se debe utilizar el estado de la orden READY_FOR_PICKUP para completar la orden con este flujo de entrega. Se espera que recibas el estado de la orden en tu webhook en el siguiente orden

  • RECEIVED

  • READY_FOR_PICKUP

  • DISPATCHED

  • CANCELLED

• Entrega del Vendedor: Debes organizar la logística para entregar las órdenes al cliente. Se debe utilizar el estado de la orden DISPATCHED para completar la orden con este flujo de entrega. Se espera que recibas el estado de la orden en tu webhook en el siguiente orden

  • RECEIVED

  • DISPATCHED

  • CANCELLED

A continuación, se muestran los posibles escenarios para completar una orden mediante el endpoint PUT, puedes encontrar el cuerpo de la solicitud para cada escenario, ajústalo según tus requisitos.

1) Completar una orden a través del endpoint PUT#

Ver las especificaciones de la API

Propósito: Completar el cumplimiento de la orden, dependiendo de los flujos de entrega elegidos, puedes completar una orden usando el estado de la orden READY_FOR_PICKUP o DISPATCHED

¿Cómo funciona?
El estado de la orden y el estado del artículo deben tenerse en cuenta al completar la orden.

• Estado del artículo

  • Se debe utilizar IN_CART para el artículo recogido

• Estado de la orden

  • READY_FOR_PICKUP para ser utilizado para el cumplimiento si estás utilizando Entrega de la Plataforma

  • DISPATCHED para ser utilizado para el cumplimiento si estás utilizando Entrega del Vendedor

La siguiente solicitud demuestra el cumplimiento en el flujo de entrega de la Plataforma. Tras una solicitud exitosa, deberías recibir un estado HTTP 200, junto con la confirmación de cumplimiento de la orden correspondiente enviada a tu webhook.

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 2,   
               "min_quantity": 0,  //optional
               "max_quantity": 2   //optional
           },
           "status": "IN_CART" // required item level status
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT", 
               "total_price": 14,       
               "quantity": 1,         
               "min_quantity": 0, //optional
               "max_quantity": 1  //optional
           },
           "status": "IN_CART" // required item level status
       }
   ],
   "status": "READY_FOR_PICKUP" or "DISPATCHED" // required order status
}

Respuesta: 200 con el cuerpo de la solicitud anterior

2) Cumplimiento parcial de una orden usando el endpoint PUT#

Ver las especificaciones de la API

Propósito: Cumplir con una orden que incluye artículos agotados y disponibles de la tienda, asegurando que no se omitan artículos de la orden.

¿Cómo funciona?
El estado de la orden y el estado del artículo deben tenerse en cuenta al completar la orden.

• Estado del artículo

  • Se debe utilizar IN_CART para el artículo recogido

  • Se puede utilizar NOT_FOUND para los artículos agotados

• Estado de la orden

  • READY_FOR_PICKUP para ser utilizado para el cumplimiento si estás utilizando Entrega de la Plataforma

  • DISPATCHED para ser utilizado para Entrega del Vendedor

La siguiente solicitud demuestra el cumplimiento en el flujo de entrega de la Plataforma. Una solicitud exitosa debe tener un estado HTTP 200 con la confirmación de cumplimiento de la orden correspondiente que se envía a tu webhook.

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 2,
               "min_quantity": 0,
               "max_quantity": 2
           },
           "status": "NOT_FOUND"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or "DISPATCHED"
}

Respuesta: 200 con el cuerpo de la solicitud anterior

3) Modificar los artículos en la orden y completar usando el endpoint PUT#

Ver las especificaciones de la API

Propósito:
Puedes ajustar la cantidad de artículos en la orden y completarla en una sola solicitud PUT. Para un artículo con `“item.pricing_type": "UNIT"` puedes modificar el campo `quantity`

Cómo funciona:

• Para ajustar la información de los artículos, se debe utilizar el objeto items.pricing

• Para modificar la quantity, asegúrate de que el valor esté dentro del rango de min_quantity y max_quantity proporcionado en la orden

• Las modificaciones de precio se aplican a los artículos con "pricing_type": "UNIT". Se debe ajustar unit_price o total_price en el cuerpo de la solicitud, pero no ambos.

• Una solicitud exitosa devuelve un estado HTTP 200 y la confirmación de cumplimiento de la orden se envía a tu webhook.

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 1, // change 
               "min_quantity": 0,
               "max_quantity": 2
           },
           "status": "IN_CART"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or DISPATCHED
}

Respuesta: 200 con el cuerpo de la solicitud anterior

4) Modificar el peso de un artículo y completar la orden usando el endpoint PUT#

Ver las especificaciones de la API

Propósito:
Puedes ajustar el peso de los artículos en la orden y completarla en una sola solicitud PUT. Para "items.pricing_type": "KG" solo debes usar el campo weight

Cómo funciona:

• Para ajustar la información de los artículos, se debe utilizar el objeto items.pricing

• weight se utilizará para la modificación, debe ser un valor decimal (por ejemplo, 1.0, 2.25, etc.)

• Para modificar el weight, asegúrate de que el valor esté en el rango de min_quantity y max_quantity del artículo

• No se permiten modificaciones de precio. Los cambios en weight ajustarán automáticamente el precio

• El campo quantity se comparte a nivel de artículo, no se requiere ninguna acción en este campo, tiene un valor predeterminado de 1

• Una solicitud exitosa devuelve un estado HTTP 200 y la confirmación de cumplimiento de la orden se envía a tu webhook.

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "KG",
               "unit_price": 85,
               "quantity": 1,
		  "weight": 1.5,
               "min_quantity": 0.5,
               "max_quantity": 2.5
           },
           "status": "IN_CART"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or DISPATCHED
}

Respuesta: 200 con el cuerpo de la solicitud anterior

5) Cancelar una orden usando el endpoint PUT#

Ver las especificaciones de la API

Propósito:
Se utiliza para cancelar una orden

Cómo funciona:

• Si el partner inicia una cancelación, se debe enviar un objeto de cancelación con una razón válida.

• Razones válidas: CLOSED, ITEM_UNAVAILABLE, TOO_BUSY

• Una solicitud exitosa devuelve el estado HTTP 200.

Solicitud:

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data 


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "KG",
               "unit_price": 85,
               "quantity": 1,
		  "weight": 1.5,
               "min_quantity": 0.5,
               "max_quantity": 2.5
           },
           "status": "NOT_FOUND"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "NOT_FOUND"
       }
   ],
       "cancellation": {
       "reason": "CLOSED", //required 
   },


   "status": "CANCELLED"  
}

Respuesta: 200 con el cuerpo de la solicitud anterior

6) Reemplazar un artículo agotado en una orden usando el endpoint PUT#

Ver las especificaciones de la API

Propósito: Reemplazar un artículo después de consultar con el cliente

¿Cómo funciona?

1. Solo se permiten los artículos disponibles en el catálogo de la tienda (activo/inactivo) para los reemplazos

2. Si item A se agrega a la orden como reemplazo de item B, item B se marcará como REPLACED y se eliminará, mientras que item A tendrá el estado IN_CART. Se debe enviar un identificador replaced_id que indique que item B se reemplaza con item A

3. Los partners deberían poder reemplazar un artículo pesable con un artículo pesable o no pesable. Los recolectores deben ingresar el peso final por KG

4. Una sola solicitud PUT puede reemplazar el artículo OOS y completar la orden

5. El número de teléfono del cliente se transmitirá a través del payload de la orden

6. Los reemplazos de artículos están disponibles para todos los Partners con integración Partner Picking que utilizan Partner API

Solicitud:

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "name": "Pepsi",
            "pricing": {							// required
                "pricing_type": "UNIT",					// required
                "unit_price": 85,   // optional,either of  unit_price or total_price to be used to change price but not both
                "quantity": 2, 						// optional,
               },"status": "REPLACED" 						// required
        },{
            "_id": "a5e42c90-351f-4c64-be7a-7dace4b96033", 	// item.id or item.sku is required
	     "sku": "146344",						//  item.id or item.sku is required
	     “replaced_id":"796ee50e-2cb5-41ec-8a06-4208fe15dcb3" //required –OOS item _id should be include as replaced_id
            "name": "cola",
            "pricing": { 							// required 
                "pricing_type": "UNIT", 
                "unit_price": 14,	 // optional,change is possible on either of  unit_price or total_price but not both
		  “quantity": 2 						// required, 
               },		
            "status": "IN_CART" 						// required
        }],"status": "READY_FOR_PICKUP" 				 	// required

Respuesta: 200 con el cuerpo de la solicitud anterior

7) Agregar un artículo adicional a la orden usando el endpoint PUT#

Ver las especificaciones de la API

Se utiliza para: si deseas agregar nuevos artículos a la orden del cliente, por ejemplo, bolsas de transporte

¿Cómo funciona?

1. Se pueden agregar varios artículos en una sola solicitud, con el estado de nivel de artículo ADDITION

2. Si un artículo ya existe en la orden, se agregará como una entrada separada siempre que se proporcionen los campos obligatorios.

3. Ejemplo: Si "Cola" está en la orden y se agrega otra "Cola", ambas aparecerán por separado con sus respectivas cantidades.

4. Si el artículo no existe para el vendedor, la solicitud falla con un error de "artículo no encontrado"

5. Si faltan los atributos requeridos para un nuevo artículo, la solicitud falla con un error de "actualización de carrito no válida"

6. Campos obligatorios para agregar artículos adicionales a la orden:

   sku: requerido para la hidratación del producto.
   pricing.quantity: requerido
   pricing.weight: requerido para artículos ponderados
   pricing.unit_price: opcional, los vendedores pueden establecer un precio unitario para el artículo adicional, anulando el precio original. Si no se proporciona, la orden utilizará el precio de la hidratación del artículo

Solicitud:

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "name": "Pepsi",
            "pricing": {							// required
                "pricing_type": "UNIT",					// required
                "unit_price": 85,   // optional,either of  unit_price or total_price to be used to change price but not both
                "quantity": 2, 						// optional,
               },"status": "REPLACED" 						// required
        },{
            "_id": "a5e42c90-351f-4c64-be7a-7dace4b96033", 	// item.id or item.sku is required
	     "sku": "146344",						//  item.id or item.sku is required
           
            "name": "cola",
            "pricing": { 							// required 
                "pricing_type": "UNIT", 
                "unit_price": 14,	 // optional,change is possible on either of  unit_price or total_price but not both
		  “quantity": 2 						// required, 
               },		
            "status": "ADDITION" 						// required new status
        }],"status": "READY_FOR_PICKUP"

Respuesta: 200 con el cuerpo de la solicitud anterior

8) Revisar los artículos y actualizar el carrito usando el endpoint PUT#

Ver las especificaciones de la API

Propósito: Si deseas actualizar el carrito para validar los cambios con nuestra plataforma en la cantidad, el peso, las adiciones o los reemplazos de los artículos antes de finalizar la orden con el estado de cumplimiento.

¿Cómo funciona?
El estado de la orden UPDATE_CART te permite modificar los artículos de una orden y recibir comentarios inmediatos.

• UPDATE_CART es solo para recibir comentarios rápidos (ejecutar validaciones y comprobaciones) mientras se recoge, no hay ningún cambio real en el estado de la orden en esta operación. No se comparte ningún evento de webhook

• Puedes llamar a PUT con UPDATE_CART tantas veces como sea necesario para asegurarte de que la orden contenga el conjunto correcto de artículos

• UPDATE_CART es un estado opcional, se puede integrar en tus operaciones existentes

• Si deseas actualizar el precio, la cantidad, agregar artículos o realizar reemplazos, puedes enviar los cambios primero con el estado UPDATE_CART. Y el estado READY_FOR_PICKUP debe usarse para completar el cumplimiento de la orden

Solicitud:

curl --location --request PUT 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data 


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7", 			// required
    "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "name": "Pepsi",
            "pricing": {							// required
                "pricing_type": "KG",					// required
                "unit_price": 85,// optional,either of  unit_price or total_price to be used to change price but not both
                "quantity": 1, 						// optional,
		"weight": 1.3 					// required for weighted items
               },"status": "IN_CART" 						// required
        },{
            "_id": "a5e42c90-351f-4c64-be7a-7dace4b96033", 	
	     "sku": "146344",						//  item.sku is required
	     “replaced_id":"null" 					//optional 
            "name": "cola",
            "pricing": { 							// required 
                "pricing_type": "UNIT", 
                "unit_price": 14,	 // optional,change is possible on either of  unit_price or total_price but not both
		  “quantity": 2 						// required
               },		
           "status": "IN_CART" 						        }],"status": "UPDATE_CART" 	// required !new status!

Recuperar órdenes históricas con nuestro endpoint GET#

Podrás solicitar información de la orden sobre:

• Orden única

• Órdenes múltiples

Recuperar detalles de una sola orden#

Propósito:
Si deseas verificar el estado de una orden individual utilizando el endpoint GET /order_id

Cómo funciona:
El endpoint GET Order ID te permite recuperar los detalles de una orden específica de nuestro Servicio de Transmisión de Órdenes.

• El Order ID debe estar en formato UUID (por ejemplo, 807c225f-ac6d-445d-a074-ea960c892ca7).

• Consulta el campo order_id en el payload de la orden.

• Solo se puede acceder a las órdenes de los últimos 60 días a través de este endpoint.

Solicitud:

curl --location  --request GET 'https://pedidosya.partner.deliveryhero.io/v2/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Authorization: ***

Respuesta: HTTP 200 con el objeto de orden

Recuperar detalles de múltiples órdenes#

Propósito:
Si necesitas obtener el historial de órdenes de una tienda específica.

Cómo funciona:
El endpoint Vendor ID te permite especificar un rango de fechas para recuperar las órdenes de la tienda. Solo se puede acceder a las órdenes de los últimos 60 días.

Parámetros de solicitud GET permitidos:

• start_time: la fecha y hora de inicio deben estar en UTC (por ejemplo, 2024-09-11T10:40:00).

• end_time: la fecha y hora de finalización deben estar en UTC (por ejemplo, 2024-08-12T12:40:00, rango máximo de 60 días).

• page_size: número de órdenes por página (predeterminado: 20).

• page: número de página de los resultados (predeterminado: 1).

Solicitud:

curl --location 'https://pedidosya.partner.deliveryhero.io/v2/chains/{chain_id}/vendors/7253942?start_time=2024-09-11T10%3A40%3A00&end_time=2024-09-12T12%3A40%3A00&page_size=&page=' \
--header 'Content-Type: application/json' \
--header 'Authorization: ***' \
--data ''

Respuesta: 200 con el objeto de matriz de órdenes

A continuación, se muestran los códigos de error observados al integrarse con los endpoints GET:**

• Se observa una solicitud incorrecta 400 cuando el cuerpo de la solicitud no es válido

• Se observa una no autorizada 401 cuando el token no es válido

• No se encuentra 404 se observa cuando la orden no está disponible en nuestra base de datos