Puedes generar hasta 11 tokens de API en el Partner Portal. Estos son tokens de portador que no tienen una fecha de caducidad y son aplicables a nivel de cadena (razón social), lo que significa que una sola clave de API puede administrar todas las tiendas en una cadena.

¿Qué detalles de la cuenta se requieren para establecer la comunicación de la API?#

Asegúrate de tener acceso al Partner Portal con el plugin Shops Integrations, consulta con tu Account Manager para obtener acceso para los usuarios requeridos
Después, se puede generar el token de API y usarse para comunicarse con nuestra API (Prerrequisito: las integraciones de deben habilitarse en el y el webhook debe configurarse en el Partner Portal)

Si una cadena existente quiere incorporar nuevas tiendas o escalar, ¿cuál es el proceso de integración?#

Para escalar la integración a nivel de cadena, se deben considerar las siguientes cosas de tu lado:

Verifica el acceso a tus nuevas tiendas en el Partner Portal y revisa las configuraciones del webhook
(Opcional) Si tienes alguna asignación interna para tu tienda, es posible que la configures directamente desde el plug-in Shops Integrations. Usa el nuevo ID de tienda o ID de vendor configurado en tus solicitudes de API

¿Cómo encuentro mi ID de Vendor/tienda de PedidosYa?#

Puedes obtenerlo directamente en Partner Portal>Shops Integrations>Configuración>Sección de Identificador de Vendedor o consultar con tu Account Manager.

¿Qué pasa si ya tengo un storeID interno y no quiero usar el storeID de la plataforma?#

Puedes configurar tu storeID interno en Partner Portal>Integraciones de Tienda>Configuración>Sección de Identificador de Vendedor. Ten en cuenta que debes usar el nuevo storeID asignado en sus solicitudes de API y que también impacta en tu integración de catálogo.

Campos de payload de la orden y esquema#

¿Qué estados de orden se envían al webhook para las Integraciones de Picking del Partner?#

Para las Integraciones de Picking del Partner, el webhook recibe notificaciones para los siguientes estados de orden:

RECEIVED: Este es el estado inicial de una orden, lo que indica que el procesamiento de la orden por parte del aún no ha comenzado. Delivery Hero automation lo envía al webhook del vendor cuando se recibe una orden.
READY_FOR_PICKUP: Este estado significa que el ha completado la recolección y el empaque de la orden, y la orden está lista para ser recogida por un repartidor. El vendor establece este estado usando un punto final PUT.
DISPATCHED: La orden ha sido enviada. Para la Entrega de Plataforma, este estado es enviado por Delivery Hero automation a los webhooks del cuando los repartidores recogen la orden de la tienda.
CANCELLED: Una orden se marca como CANCELLED si la orden es cancelada por el cliente, el repartidor o usted. No se enviará ningún webhook en las cancelaciones que se originen en la solución de Picking del .

¿Cómo puedo sacar el máximo provecho de la integración de Picking del Partner usando mi webhook?#

Los estados de orden RECEIVED READY_FOR_PICKUP DISPATCHED y CANCELLED deben ser consumidos por tu webhook
Configuraciones: Para asegurar tus configuraciones de webhook en el Partner Portal, se pueden utilizar contraseñas, que pueden ser cualquier cadena, también acomodamos el mecanismo de autenticación básica.
- Por ejemplo, si el servicio de webhook usa partner como el nombre de usuario y randompassword como la contraseña, entonces el valor en codificación Base64 de partner: *randompassword es cmFuZG9tcGFzc3dvcmQ=
- Entonces, el campo del header de Autorización aparecerá como: Basic cmFuZG9tcGFzc3dvcmQ= (esto debe agregarse al campo contraseña en el Partner Portal)\
  Nota
  Asegurar tu webhook usando una contraseña es obligatorio
Aprovechando el endpoint PUT, asegúrate de haber cubierto los siguientes casos de uso con tu propia solución de picking
1. Cumplimiento completo de la orden
2. Cumplimiento parcial de la orden
3. Reemplazos de artículos
4. Adiciones de artículos
5. Actualizaciones del carrito
6. Cumplir con la orden que contiene artículos ponderados, es decir, pricing_type: "KG"
7. Modificar la cantidad de la orden en los artículos con pricing_type: "UNIT" (los ajustes de precio son posibles a un valor más bajo en cualquiera de los campos unit_pice o total_price, pero no en ambos)
8. Cancelación de la orden, incluidas las razones de cancelación apropiadas

¿Cuáles son las limitaciones de la Integración de Picking del Partner?#

No se permiten modificaciones de precio en artículos pesables, es decir, pricing_type: "KG"
El external_order_id de la plataforma no funciona para recuperar la orden, mientras que al usar el endpoint GET para recuperar una sola orden, debe usar el order_id (tipo uuid) del paylod de la orden.
Asegúrate de que tus solicitudes de API (GET o PUT) a nuestro servicio no excedan las 60 solicitudes por minuto.

¿Cuáles son los campos en el payload de la orden y cómo puedo usarlos?#

Datos del cliente:

En el campo comments se envía el email del cliente de forma tokenizada para que puedas enviarle la factura de forma digital. Por temas de seguridad la vida del email es de 12 horas y sólo se puede enviar un correo al email que se comparte. El correo que envíes será redirigido al email real del cliente.

Payload de orden de ejemplo

{
order_id: "807c225f-ac6d-445d-a074-ea960c892ca7",// usado en el punto final GET
external_order_id: "qktu-ul1p", 		// visible en <Note>Pelican</Note>
order_code: "546",
client: { 					//contiene información de la tienda
id: "22438",
chain_id: "0aa64dc1-280b-4d1c-972a-28a15a14382a",
name: "qktu - chainname",
country_code: "tw",
store_id: "qktu",
external_partner_config_id: "462"  //asignación interna para sus tiendas
},
customer: {					// la información del cliente está enmascarada
_id: "twxqg33o",
national_id: "",
tax_id: "",
first_name: "于**",
last_name: "**",
phone_number: "+88693****651",
delivery_address: {
country: "",
city: "",
street: "",
number: "",
latitude: 0,
longitude: 0,
company: "",
block: "",
building: "",
apartment: "",
entrance: "",
intercom: "",
floor: "",
suburb: "",
zipcode: "",
instructions: "",
formattedAddress: ""
}
},
comment: "",
items: [			// información a nivel de artículo
{
_id: "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",
sku: "222316",
barcode: [
4710036604597
],
name: "Cuatro Quesos La Serenísima Finlandia Light en Hebras 130 g",
pricing: {            // contiene información de los artículos cumplidos
pricing_type: "UNIT",
unit_price: 85,
vat_percent: 0,
total_price: 170,
quantity: 2,
min_quantity: 0,
max_quantity: 2
},
original_pricing: { // contiene información del artículo en la colocación de la orden
pricing_type: "UNIT", // fo UNIT quatity hold information of any changes
unit_price: 85,
vat_percent: 0,
total_price: 170,
quantity: 2,
min_quantity: 0,
max_quantity: 2
},
container_deposit: 0,
discount: 0,
instructions: "",
status: "NOT_PROCESSED"          // estado a nivel de artículo
},
{
_id: "a5e42c90-351f-4c64-be7a-7dace4b96033",
sku: "146344",
barcode: [
4710098163773
],
name: "Manzana Red Delicious",
pricing: {
pricing_type: "KG",–> // cuando el tipo de precio es KG, el campo de peso está disponible en el objeto de precio, la cantidad por defecto es 1
unit_price: 7,
vat_percent: 0,
total_price: 14,
weight: 2.0,
quantity: 1,
min_quantity: 0,
max_quantity: 1
},
original_pricing: {
pricing_type: "KG",
unit_price: 7,
vat_percent: 0,
total_price: 14,
weight: 2.0,
quantity: 1,
min_quantity: 0,
max_quantity: 2
},
container_deposit: 0,
discount: 0,
instructions: "",
status: "NOT_PROCESSED" // estado a nivel de artículo
}
],
order_type: "DELIVERY",
transport_type: "LOGISTICS_DELIVERY", // tipo de flujo de entrega
payment: {
sub_total: 184,  // suma de los artículos totales
order_total: 177, // cantidad pagada por el cliente contiene tarifas, descuentos
delivery_fee: 0,
service_fee: 2.39,
difference_to_minimum: 0,
discounts: [
{
name: "vh8o1buy",
value: -9.2
}
],
discount: -9.2,
container_charge: 0,
total_taxes: 8.32,
additional_fees: {
PriorityDeliveryFee: 0
},
type: "PAID"
},
cancellation: {
reason: "",
cancelled_by: "",
post_pickup: true			// solo visible para las órdenes canceladas después del cumplimiento de la orden
},
status: "CANCELLED", // estado de la orden
sys: {
created_at: "2023-09-01T07:41:17.733Z",
created_by: "Order Fulfilment",
updated_at: "2023-09-01T07:45:45.863Z",
updated_by: "Order Fulfilment",
webhook_status: ""
},
promised_for: "2023-09-01T08:06:11Z",
isPreorder: false
}

¿Debo validar los detalles del cliente proporcionados en el payload de la orden?#

Dependiendo de cómo pretendas enrutar las órdenes a una tienda específica, puedes usar la siguiente información de campo para identificar y validar con precisión la tienda. store_id: xxxx, – Identificador de la tienda en los sistemas de la plataforma external_partner_config_id: xxxx– si la tienda/punto de venta del Partner tiene algún identificador interno, debe asignarse a este campo. Dependiendo de cómo desees dirigir las órdenes a una tienda específica, puedes usar la siguiente información de campo para validar la tienda.

Nota

Si tienes integración SFTP, cambiar esta configuración podría afectar las actualizaciones SFTP, se requiere revisión del AM

¿Cuál es la diferencia entre "order_id", "external_order_id" y "order_code" y cuál debe usar el Partner para fines de conciliación?#

order_id: 7384a9e4-c4e1-4820-873e-2cc637acec78– Identificador único para la orden utilizada en nuestros servicios backend. Si deseas consultar una sola orden usando el punto final GET, debes usar order_id

external_order_id: mxuv-2439-9sa5– ID de orden de la plataforma, que se muestra en el dispositivo , external_order_id podría usarse en tu proceso de conciliación

order_code: es un valor incremental (se restablece después de 9999) en las órdenes utilizadas por los repartidores para recoger las órdenes de la tienda

¿Cuál es la diferencia entre "sub_total" y "order_total"? ¿Cuál es el total final de la orden que el Partner debe considerar?#

sub_total: Se refiere al valor total de los artículos de la orden, incluidos los impuestos a nivel de artículo, pero excluyendo cualquier descuento a nivel de orden (como códigos de cupón o descuentos aplicados a nivel general de la orden). Debes usar sub_total cuando desees validar el valor acumulativo de todos los artículos en la orden
order_total: Esta es la cantidad final pagada por el cliente por la orden. Incluye todos los precios de los artículos, las tarifas de envío y los descuentos (como códigos de cupón o descuentos aplicados a nivel general de la orden)

¿Qué pasa si el artículo tiene precios basados en el peso?#

Cuando un artículo tiene precios basados en el peso, pricing_type será "KG" a nivel de artículo en el payload de la orden. Para tales artículos, el campo de cantidad siempre tendrá un valor predeterminado de 1, y un campo de peso estará presente con un valor decimal para indicar el peso del artículo.

¿Cómo identificar los artículos con cantidad finita y los artículos con cantidades en KG (productos pesables) en el payload de la orden?#

Cada artículo en la orden tiene objetos pricing y original_pricing, & ambos objetos tienen el campo quantity
El objeto pricing contiene la cantidad recogida (ajustada por el recolector), consulta el campo Items.pricing.quantity
El objeto original_pricing contiene la cantidad ordenada por el cliente, consulta el campo Items.original_pricing.quantity
Para los artículos con cantidad finita, pricing_type será UNIT, compartiendo ambos objetos de precio y original_pricing. El objeto de precio contiene la cantidad recogida por el recolector. Items.pricing.quantity

{
  "pricing": {
    "pricing_type": "UNIT",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "min_quantity": 0,
    "max_quantity": 2
  },
  "original_pricing": {
    "pricing_type": "UNIT",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 1.38,
    "quantity": 2,
    "min_quantity": 0,
    "max_quantity": 2
  },
}

Para los artículos con weight, pricing_type será KG, compartiendo ambos objetos pricing y original_pricing. El objeto de precio contiene el peso real recogido/cumplido (valor decimal) por el recolector, es decir, Items.pricing.weight. También compartimos la cantidad para los artículos pesables, sin embargo, este será el valor predeterminado 1 (se puede ignorar si le resulta inútil)

{
  "pricing": {
    "pricing_type": "KG",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "weight": 1.0,
    "min_quantity": 0,
    "max_quantity": 2
  },
  "original_pricing": {
    "pricing_type": "KG",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "weight": 1.0,
    "min_quantity": 0,
    "max_quantity": 2
  }
}

¿Cómo puedo saber si una orden fue realmente recogida después de ser cancelada? Necesito saber si debe tratarse como una venta final.#

Solicita al equipo de Soporte de Integraciones que habilite el campo post_pick_up. Esta es una adición al objeto de cancelación existente específico para el caso de uso: cancelación de la orden después de la recogida del repartidor. Para todos los demás escenarios de cancelación: SIN CAMBIOS, el campo post_pick_up no es visible.

Escenario: cancelación de la orden después de la recogida del repartidor:
…
"cancellation": {
    "reason": "TECHNICAL_PROBLEM",
    "cancelled_by": "CUSTOMER",
    "post_picked_up": true
  },
..
Para otros escenarios de cancelación:
…
"cancellation": {
    "reason": "TECHNICAL_PROBLEM",
    "cancelled_by": "CUSTOMER",
  },

¿Cómo valido la cancelación de la orden? ¿Debo usar el mismo webhook o un punto final diferente?#

La cancelación puede ocurrir por parte del cliente, el vendor y la logística. Cuando el evento de cancelación ocurre durante el ciclo de vida de la orden. El estado CANCELLED se enviará al mismo webhook configurado en el Partner Portal.

¿Qué pasa si mi servicio de webhook no está accesible? ¿La integración de Picking del Partner admite reintentos en nuestro webhook?#

Admitimos mecanismos de reintento en los casos en que su servicio de webhook no responde en 10 segundos. El sistema intentará hasta 5 reintentos, cada uno espaciado 10 segundos. Es importante que implementes un manejo adecuado en tu extremo para administrar posibles payloads de órdenes duplicadas, de modo que las entregas repetidas de webhook no resulten en el procesamiento de la misma orden varias veces.

Acceso al Partner Portal#

¿Qué es el Partner Portal y cómo obtengo acceso?#

El Partner Portal es una herramienta de back office mediante la cual puedes administrar tus tiendas. Cuando te incorporas a nuestra plataforma, nuestro equipo de Account Management te proporcionará el acceso. Dependiendo de tus privilegios de uso, también puedes administrar las configuraciones de webhook y token.

Las siguientes actividades se pueden administrar desde el Partner portal:

Configuraciones de integración
- Operaciones de la tienda
- Crear promociones
- Actualizar la disponibilidad y los precios de los productos
- Revisar las órdenes en todas sus tiendas
- Identificar problemas y realizar la resolución de problemas inicial

¿Cómo accedo al Plugin Shops Integrations?#

Todos los de Local Shops de cualquier tamaño pueden acceder al plugin de Shops Integrations en el Partner Portal, tu Account Manager te dará acceso o durante el registro con nosotros.
Se recomienda limitar el acceso a los plugins de Tiendas en el Partner Portal solo a aquellos que necesitan realizar una función para tu negocio; esto se debe a que el Partner Portal puede contener información confidencial, es decir, las configuraciones de webhook
Comunícate con su Account Manager si no sabe cómo obtener acceso al Partner Portal

¿Dónde puedo obtener más apoyo?#

Si tienes alguna pregunta sobre la integración puedes contactar al equipo Soporte de Integraciones a través del correo [email protected] o agendando una reunión en este link.

Si tienes un issue, pónte en contacto con el equipo de Soporte de Integraciones en el correo [email protected] o repórtalo issue en este link y proporciona: