Preguntas frecuentes#

Haz clic abajo para ir a los temas:

• ¿Cómo le saco el máximo provecho a la integración de picking de Pelican?

• ¿Cuáles son las limitaciones de la Partner API/Órdenes (Pelican)?

• ¿Cómo accedo al plugin Shops Integrations?

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

• ¿Cuál es la diferencia entre "order_id", "external_order_id" y "order_code" y cuál debo usar para fines de conciliación?

• ¿Cómo genero credenciales para usar Partner API/Órdenes?

• ¿Cómo puedo saber si un pedido fue recogido después de ser cancelado? Necesito saber si debe tratarse como una venta final.

• ¿Cómo identificar los artículos con cantidad finita y los artículos con cantidades en KG (productos pesables) en el payload del pedido?

• ¿Necesitamos validar los detalles del cliente del objeto cliente proporcionado en el payload del pedido?

• ¿Cómo puedo usar un entorno de prueba para las integraciones de gestión de pedidos?

• ¿Cuál es la diferencia entre "sub_total" y "order_total"? ¿Cuál es el total final del pedido que el Partner debe considerar?

• ¿Cuáles son los campos en el payload del pedido y cómo puedo usarlos?

¿Cómo le saco el máximo provecho a la integración de picking de Pelican?#

• Estados de pedido READY_FOR_PICKUP y CANCELLED para ser consumidos por el webhook

• Configuraciones: Para asegurar tus configuraciones de webhook en Partner Portal, se pueden utilizar contraseñas para tal fin, que pueden ser cualquier cadena de texto, también admitimos el mecanismo de autenticación básica.

  • Por ejemplo, si el servicio webhook utiliza partner como nombre de usuario y randompassword como contraseña, entonces el valor en codificación Base64 de partner: *randompassword, es cmFuZG9tcGFzc3dvcmQ=

  • Entonces, el campo del encabezado de autorización aparecerá como: Basic cmFuZG9tcGFzc3dvcmQ= (esto debe agregarse al campo secret en el Partner Portal)

¿Cuáles son las limitaciones de Partner API/Órdenes (Pelican)?#

• Los nuevos pedidos creados por los clientes en la aplicación de la plataforma no se reenvían directamente al webhook, solo los pedidos completados por los pickers se transmiten al webhook con el estado READY_FOR_PICKUP

• Se espera que recibas solo READY_FOR_PICKUP y CANCELLED como estado del pedido en su webhook

¿Cómo accedo al plugin Shops Integrations?#

• Todos los partners de Local Shops de cualquier tamaño pueden acceder al plugin Shops Integrations en el Partner Portal, tu Account Manager te dará acceso.

• 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, configuraciones de webhook

• Comunícate con tu Account Manager si no sabes cómo obtener acceso al Partner Portal

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

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 brindará 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 pedidos en todas tus tiendas

  • Identificar problemas y realizar la resolución de problemas inicial

¿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 el pedido utilizado en nuestros servicios de backend. Si deseas consultar un solo pedido utilizando el punto final GET, debe usar order_id

external_order_id: 1622060003: ID de pedido de la plataforma, que se muestra en el dispositivo Pelican, 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 los pedidos utilizados por los repartidores para recoger los pedidos de la tienda

¿Cómo genero credenciales para usar Partner API/Órdenes?#

Consulta la sección de administración de tokens aquí

¿Cómo puedo saber si un pedido fue recogido después de ser cancelado? Necesito saber si debe tratarse como una venta final.#

Solicita al Account Manager que habilite el campo post_pick_up. Este es un campo booleano que estará disponible en el objeto de cancelación. Se establecerá en "true" cuando el pedido se cancele después de que el repartidor haya recogido el pedido de la tienda.

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

• Cada artículo en el pedido tiene objetos pricing y original_pricing, y ambos objetos tienen el campo quantity

• El objeto pricing contiene la cantidad recogida (ajustada por el picker), consulta el campo Items.pricing.quantity

• El objeto original_pricing contiene la cantidad pedida 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 precios y original_pricing. El objeto de precios contiene la cantidad recogida por el picker. 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(productos pesables), pricing_type será KG, compartiendo ambos objetos de precios y original_pricing. El objeto de precios contiene el peso real recogido (valor decimal) por el picker, es decir, Items.pricing.weight. También compartimos la cantidad para los artículos pesables, sin embargo, este será el valor predeterminado 1 (lo puedes ignorar si no te resulta ú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
  }
}

¿Necesitamos validar los detalles del cliente del objeto cliente en el payload del pedido?#

Si está buscando ordenar o filtrar pedidos para una tienda o punto de venta específico, puedes usar los siguientes campos del payload: store_id: Identificador único de la tienda dentro de nuestra plataforma. external_partner_config_id: Usa esto para asignar tu propio identificador interno de tienda/punto de venta. Puedes configurar esto desde el Partner Portal Importante: Si estás utilizando la integración SFTP, modificar esta configuración puede afectar tus actualizaciones SFTP. Consulta a tu Account Manager antes de realizar cualquier cambio.

¿Cómo puedo usar un entorno de prueba para las integraciones de gestión de pedidos?#

• Tu Account Manager creará una nueva tienda que será utilizada exclusivamente para pruebas. Te compartirá el ID de esta tienda, nombre y dirección.

• Tu Account Manager te creará también un usuario en Pelican (para que puedas probar el flujo completo de las órdenes gestionandolas desde la aplicación móvil de Pelican) y en Vendor Portal (donde configurarás el webhook).

• Deberás compartirle a tu Account Manager un correo al que tengas acceso pero NO exista en PedidosYa. Con este correo, se creará un usuario de pruebas para la aplicación de PedidosYa con el que podrás hacer pedidos en la tienda de pruebas (siguiendo el flujo de un usuario real que pide a través de la app móvil).

• Una vez que tengas todos los accesos deberás en primer lugar configurar el webhook y obtener el token en Vendor Portal. Luego, podrás crear órdenes en la aplicación móvil de PedidosYa en tu tienda de pruebas (ingresando como un usuario real pero con tu usuario de prueba), gestionar la orden en Pelican y al marcarla como READY_FOR_PICKUP, la recibirás en el webhook configurado.

¿Cuál es la diferencia entre sub_total y order_total? ¿Cuál debe usar el partner como total final del pedido?#

sub_total: el valor de los artículos del pedido incluye el impuesto y los descuentos a nivel de artículo ya están incluidos en el precio order_total: valor final que los clientes pagan por el pedido incluye el sub_total, los descuentos a nivel de pedido y cualquier tarifa de servicio o entrega adicional sub_total para ser utilizado cuando solo desee validar el valor total de los artículos

¿Cuáles son los campos en el payload del pedido y cómo puedo usarlos?#

payload de pedido de muestra

{
order_id: "807c225f-ac6d-445d-a074-ea960c892ca7",// utilizado en el punto final GET
external_order_id: "qktu-ul1p", 		// visible en Pelican
order_code: "546",
client: { 					// contiene información de la tienda
id: "22438",
chain_id: "0aa64dc1-280b-4d1c-972a-28a15a14382a",
name: "qktu - chainname",
country_code: "ar",
store_id: "123456",
external_partner_config_id: "462"  // asignación interna para sus tiendas
},
customer: {					// la información del cliente está enmascarada
_id: "5993893",
national_id: "3975****",
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": "Si algún producto no está disponible: Elegir reemplazos | Email del Cliente: [email protected]",  
items: [			// información a nivel de artículo
{
_id: "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",
sku: "222316",
barcode: [
"07790742667328"
],
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 al realizar el pedido
pricing_type: "UNIT", // para la cantidad de UNIT, mantenga información de cualquier cambio
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, // peso pickeado
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, // peso solicitado por el cliente
quantity: 1,
min_quantity: 0,
max_quantity: 2
},
container_deposit: 0,
discount: 0,
instructions: "",
status: "IN_CART" // estado a nivel de artículo
}
],
order_type: "DELIVERY",
transport_type: "LOGISTICS_DELIVERY", // tipo de flujo de entrega
payment: {
sub_total: 184,  // suma del total de artículos
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 pedidos cancelados después del cumplimiento del pedido
},
status: "CANCELLED", // estado del pedido
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
}

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.

Estados de la orden: los estados que recibirás en el webhook son los siguientes:

• READY_FOR_PICKUP - Se envía una vez la orden es cerrada (checkout) en Pelican y ya está lista para ser retirada por repartidor.

• CANCELED - Se envía este estado si la orden ha sido cancelada por PedidosYa(validar razón y quién canceló en order.cancellation[...]).

Motivos de cancelación:

• CLOSED 

• ITEM_UNAVAILABLE

• TOO_BUSY

Estados de los productos: 

• NOT_PROCESSED: estado inicial de un producto recibido por el webhook

• NOT_FOUND: producto no encontrado en tienda

• IN_CART: producto agregado al carrito por el picker

• REPLACED: productos que fueron reemplazados y no se entregan al cliente. Si A es reemplazado por B. A tendrá el estado REPLACED y B el estado IN_CART

Información de los productos: 

• En el arreglo "pricing" de los productos se indica la cantidad final (quantity) y precio con el descuento aplicado a nivel de unidad (unit_price) y del total de unidades pickeadas (total_price).

• Si tienes productos PESABLES, el peso del producto se indicará en el campo weight que aparecerá dentro del arreglo del producto, como se ve en el ejemplo. Además el campo "pricing_type" seá KG. Puedes consultar con tu Account Manager si tienes productos con estas características. 

Tipos de pago:

En el campo "type", dentro del arreglo "payment", podrás recibir uno de los siguientes métodos de pago:

• CASH_ON_DELIVERY = Pago en efectivo

• CARD_ON_DELIVERY = Pago con tarjeta pero en el domicilio del cliente

• PAID = Pago online, esto son todos los pagos con tarjeta desde la app