Embedded Files
A través de nuestra API Rest, podrás integrarte para automatizar
la gestión de tu catálogo en PedidosYa.
Proceso
Proceso
PASO 1
Contacto
Leer la documentación.
PASO 2
Acceso
Comparte a tu Ejecutivo de Cuenta un correo al que tengas acceso pero NO exista en Pedidosya.
Recibirás la dirección y nombre de tu tienda de pruebas. Además te darán acceso a ella desde el Vendor Portal, donde podrás generar el token y configurar el webhook.
Te llegará un email del equipo de Soporte de Integraciones para que tengas el primer contacto con ellos.
PASO 3
Desarrollo
Podrás consultarle al equipo de Soporte de Integraciones las dudas que tengas.
PASO 4
Test + Homologación
Deberás probar todas las funcionalidades y comunicarle al equipo de Soporte para que te den feedback.
Deberás coordinar una reunión de homologación con el equipo de Soporte de Integraciones a través del siguiente link.
PASO 5
Live
Puesta en marcha de la integración en todas tus tiendas online.
PASO 6
Issues
Puedes contactar a tu Ejecutivo de Cuenta o comunicarte con Ayuda en línea a través del Vendor Portal.
Accesos
Accesos
Comparte a tu Ejecutivo de Cuenta un correo al que tengas acceso pero NO exista en Pedidosya.
El equipo de Soporte de Integraciones creará un usuario de pruebas con el correo compartido, que sólo podrá ser utilizado para pruebas (no se podrán realizar pedidos reales). Podrás ver tu tienda de pruebas desde el Vendor Portal y en la aplicación de PedidosYa, buscándola con la dirección y el nombre que te compartirá tu Representante de cuenta (ingresando a la app con el usuario de pruebas). Allí podrás verificar que todo lo que gestiones se vea impactado correctamente.
Realiza tu gestión de acceso desde el Vendor Portal.
Autenticación
Ingresa al Vendor portal y dirígite a la sección Shops Integrations.
Ingresa a la pestaña Gestión de Tokens. Desde allí, podrás solicitar un token que luego deberás utilizar en cada request a Partner API.
Toca en Generar nuevo token. Como puedes ver en la imagen, al obtener el token es necesario guardarlo inmediatamente ya que luego no se puede volver a visualizar.
Ten en cuenta que este token aplicará a todos los vendors de la razón social.
Configuración de la URL de webhook
Ingresa al Vendor Portal y, dentro de la sección Shop Integrations, ve hasta la pestaña Actualización del surtido.
En el lateral derecho podrás configurar el webhook donde quieres recibir las notificaciones. A ese webhook le puedes configurar una clave, si lo deseas.
Si especificas una clave en la configuración del webhook, llegará como un header authorization del tipo bearer:
Casos de uso
Casos de uso
Asociación de Productos
Con esta funcionalidad podrás asociar un producto existente en el catálogo global de PedidosYa al catálogo particular de tus tiendas, mediante el Barcode (GTIN) de un producto.
Esta asociación te permitirá crear el producto en tu catálogo, especificando cierta información:
SKU
Categoría
Precio
Disponibilidad
Máxima cantidad de compra
Ten en cuenta que:
- La lista de productos no puede estar vacía y puede tener hasta un máximo de 10.000 productos.
- No se pueden asignar productos pesables a través de esta API. Contacta con nosotros para asignar ese tipo de productos.
Este es la información que irá en el request para asociar productos:
Barcode: es el identificador único del producto. Este campo no debe estar vacío. Cada código de barras debe contar únicamente de números y una longitud igual a 14 (si tu código de barras tiene menor longitud, deberás agregarle ceros a la izquierda). Cada producto tendrá un único GTIN.
Category Ids (category_ids): indica la categoría o categorías a las que pertenece el producto. La lista no debe estar vacía y no puede ser mayor que 5. Para conocer este valor deberás consultar el endpoint /categories.
SKU: es el código identificador del producto. Puedes incluir números y letras. Debe tener hasta 64 dígitos. Cada producto tendrá un único SKU.
Precio (price): indica el precio del producto. Debe ser mayor que 0 y tiene un máximo de 2 decimales; de lo contrario, se producirá un error de validación.
Disponibilidad del producto: debes informar sólo uno de los siguientes campos:
Estado del producto (active): indica si el producto está activo o no (es binario). Este campo es opcional y viene FALSE por defecto.
Stock del producto (quantity): número entero que indica la cantidad de unidades que tienes del producto en stock.
Cantidad máxima de ventas (maximum_sales_quantity): Si corresponde, especifica la cantidad máxima de ventas para el producto por orden. Debe ser mayor a 0. Este es un campo opcional y, si está vacío, entonces la venta será ilimitada.
Diagrama de secuencia:
¿Cómo asociar un producto vía API?
Realiza el request associated product:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/{vendorId}/products' \
--header 'Accept: application/json' \
--header 'Authorization: {validToken}' \
--header 'Content-Type: application/json' \
--data '{
"products": [
{
"barcode": "07441003500532",
"category_ids": [
"42507fb7-a0af-4419-a079-f97e4ad4f7e7"
],
"sku": "SKUCOCATEST",
"price": 45,
"active": true,
"maximum_sales_quantity": 10
}
]
}'
2. Obtendrás el siguiente response:
{
"success": true,
"job_type": "ASYNC",
"job_id": 47457439
}
3. Luego de que realices el request, llegará el siguiente request al webhook configurado:
{
"job_id":47457439,
"platform_vendor_id":"364124",
"status":"COMPLETED",
"download_url":"https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/f0f9ef4439a89c2d20c7f593931d97a612d3b9d82b08ee3fadd98ba1519464ab/job/47457439"
}
4. Por último, con el siguiente request descargas el archivo .CSV con el resultado del procesamiento:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/f0f9ef4439a89c2d20c7f593931d97a612d3b9d82b08ee3fadd98ba1519464ab/job/47457439' \
--header 'Accept: text/csv' \
--header 'Authorization: {validToken}' \
--data ''
Debes tener en cuenta que el header Accept debe ir como text/cvs para poder descargar el archivo .CSV.
La respuesta será el archivo .CSV con el siguiente formato:
"sku","code","state","errors","row_number","piece_barcode"
"SKUCOCATEST","","new","null","2","07441003500532"
Casos de error
Casos de error
1. Error por asociar un producto por un Barcode inexistente. En ese caso la API retornará error http 400:
{
"timestamp": "2023-11-30T20:11:39.749+00:00",
"path": "/api/assortment/v1/vendors/364124/products",
"status": 400,
"error": "Bad Request",
"message": "Invalid barcode format",
"requestId": "c2a4a39b-881952"
}
2. Error por asociar un producto con un SKU ya existente en tu catálogo. Ese error no se devolverá de forma en tiempo real, si no que llegará al webhook:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}' \
--data '{
"products": [
{
"barcode": "7730132001431",
"category_ids": [
"42507fb7-a0af-4419-a079-f97e4ad4f7e7"
],
"sku": "SKUCOCATEST",
"price": 450,
"active": true,
"maximum_sales_quantity": 10
}
]
}'
Obtendrás el siguiente response:
{
"success": true,
"job_type": "ASYNC",
"job_id": 47458197
}
El mensaje recibido en el webhook será así:
{
"job_id":47458129,
"platform_vendor_id":"364124",
"status":"COMPLETED",
"download_url":"https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/7a1b659a011462fb56891e51551364d0fb1eaee7da7e1309e75a7fa3b8f2f989/job/47458129"
}
Deberás procesar siempre la respuesta del webhook donde podrás ver el error:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/7a1b659a011462fb56891e51551364d0fb1eaee7da7e1309e75a7fa3b8f2f989/job/47458129' \
--header 'Accept: text/csv' \
--header 'Authorization:{tokenValido}' \
--data ''
Obtendrás el siguiente response:
"sku","code","state","errors","row_number","piece_barcode"
"SKUCOCATEST","","error","{sku=entered combination of sku, master_product_code and pieceBarcode does not match with existing values in the database}","2","7730132001431"
Consideraciones de performance
Si la implementación está pensada para realizar envíos en lote o de forma masiva, utiliza la posibilidad de enviar una lista de productos a asociar que brinda el servicio. De esta forma optimizarás el procesamiento.
No envíes reiteradamente las asociaciones. Deben ser enviadas una vez y esperar la respuesta que llegará al webhook.
No enviar más de 2.000 request por hora.
2. Actualización de un producto (precio "price" / disponibilidad "active" / cantidad máxima "maximum_sales_quantity" ).
El campo active es un campo binario (true/false).
Diagrama de secuencia:
Deberás enviar el siguiente request para la actualización de precio y disponibilidad de tus productos:
curl --location --request PUT 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/product' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}' \
--header 'Content-Type: application/json' \
--data '{
"sku": "L7TIWZ",
"price": 101,
"active": false
}'
2. Obtendrás este response:
{
"success": true
}
3. El response con un http 200 OK y el campo con el campo success = true en el body indica que se procesó correctamente la actualización de información del producto.
Request para eliminar un producto
Ten en cuenta que no existe un endpoint para eliminar un producto. Por eso si deseas eliminar (apagar) un producto, utiliza active = false (eliminación lógica) para emular ese caso de uso:
curl --location --request PUT 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/product' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}' \
--header 'Content-Type: application/json' \
--data '{
"sku": "SKUACEITETEST",
"price": 101,
"active": false
}'
Obtendrás este response:
{
"success": true
}
Si deseas actualizar solo un campo del producto (por ejemplo: precio), el request sería así:
curl --location --request PUT 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/product' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}' \
--header 'Content-Type: application/json' \
--data '{
"sku": "L7TIWZ",
"price": 101
}'
Consideraciones de performance
Si la implementación está pensada para realizar envíos en lote o de forma masiva, utiliza la posibilidad de enviar una lista de productos a actualizar que brinda el servicio. De esta forma optimizarás el procesamiento.
No envíes más de 2.000 request por hora.
No envíes actualizaciones de todo el catálogo. Solo envía actualizaciones de aquellos productos en los que quieres impactar modificaciones.
3. Actualización de productos en lote o de forma masiva:
Esta funcionalidad te permitirá enviar actualizaciones para varios productos al mismo tiempo. Es importante tener en cuenta que, a diferencia de la actualización individual, este no es un proceso síncrono (en tiempo real).
Al utilizarlo obtendrás una respuesta asíncrona en el webhook con la información del procesamiento.
Con este endpoint, siempre que actualices más de un producto a la vez, podrás informar la disponibilidad de tus productos con el campo quantity (stock numérico) o con el campo active (campo binario). Si actualizas un único producto, deberás informar la disponibilidad con el campo active.
Diagrama de secuencia:
Deberás enviar el siguiente request:
curl --location --request PUT 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products-bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {validToken}' \
--data '{
"products": [
{
"sku":"01466",
"active":true,
"price":79.9
},
{
"sku":"SKUCOCATEST",
"active":true,
"price":249.0,
"maximum_sales_quantity":6
}
]
}'
2. Obtendrás este response:
{
"success": true,
"job_type": "ASYNC",
"job_id": 48519639
}
3. Inmediatamente después de realizar el request, llegará el siguiente request al webhook configurado:
{
"job_id": 48519639,
"platform_vendor_id": "364124",
"status": "COMPLETED",
"download_url": "https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/8f0ceea76cc7e31f8cd1fafa86cf03d36352c3defccdbf1c2393b7705f44eacf/job/48519639"
}
4. Por último, debes realizar un http GET para obtener el catálogo a la URL recibida en download_url:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/import/133970/8f0ceea76cc7e31f8cd1fafa86cf03d36352c3defccdbf1c2393b7705f44eacf/job/48519639' \
--header 'Accept: text/csv' \
--header 'Authorization: {tokenValido}' \
--data ''
Nota: Es importante que envíes el header Accept con text/csv: --header 'Accept: text/csv' \
Consideraciones de performance
Los payloads que envíes podrán tener hasta 100 MB de tamaño.
4. Exportar el catálogo
Esta funcionalidad te permitirá obtener todos los productos del catálogo de un vendor o tienda.
Diagrama de secuencia:
Deberás enviar el siguiente request:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/export' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}' \
--header 'Content-Type: application/json' \
--data ''
2. Obtendrás este response:
{
"job_id": 47455633
}
3. Inmediatamente después de realizar el request, llegará el siguiente request al webhook configurado:
{
"job_id":47455633,
"platform_vendor_id":"364124",
"status":"COMPLETED",
"download_url":"https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/export/133970/6b852fdf7b5d9fd4ab901e5bfffd31c14e112bea1f5a266144f5c01d9f0c5105/job/47455633"
}
4. Por último debes realizar un http GET para obtener el catálogo a la URL recibida en download_url.
curl --location --request GET 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/products/export/133970/6b852fdf7b5d9fd4ab901e5bfffd31c14e112bea1f5a266144f5c01d9f0c5105/job/47455633' \
--header 'Accept: text/csv' \
--header 'Authorization:{tokenValido}' \
--header 'Content-Type: application/json' \
--data ''
Nota: Es importante que envíes el header Accept con text/csv: --header 'Accept: text/csv' \
Este será el formato del archivo .CSV retornado:
"sku","barcode","price","active","maximum_sales_quantity"
"01466","00000003456217","666.0","1","0"
"SKUACEITETEST","07730132001431","101.0","0","15"
"L7TIWZ","","101.0","1","0"
"SKUCOCATEST","07441003500532","45.0","0","10"
"02851400109002","02851400109002","200.0","1","2"
"02851400008008","02851400008008","200.0","1","0"
5. Obtener listado de categorías
Con esta funcionalidad podrás obtener todas las categorías configuradas para una tienda específica.
Diagrama de secuencia:
Deberás enviar este request:
curl --location 'https://partners-pedidosya.deliveryhero.io/api/assortment/v1/vendors/364124/categories' \
--header 'Accept: application/json' \
--header 'Authorization: {tokenValido}\
2. Obtendrás el siguiente response:
{
"categories": [
{
"global_id": "7b444a78-4bce-475d-ac13-dad9c5c4ddf8",
"details": {
"name": {
"es_AR": "Root",
"es_BO": "Root",
"es_CL": "Root",
"es_CR": "Root",
"es_DO": "Root",
"es_EC": "Root",
"es_GT": "Root",
"es_HN": "Root",
"es_NI": "Root",
"es_PA": "Root",
"es_PE": "Root",
"es_PY": "Root",
"es_SV": "Root",
"es_UY": "Root",
"es_VE": "Root"
},
"description": {
"es_AR": "Root",
"es_BO": "Root",
"es_CL": "Root",
"es_CR": "Root",
"es_DO": "Root",
"es_EC": "Root",
"es_GT": "Root",
"es_HN": "Root",
"es_NI": "Root",
"es_PA": "Root",
"es_PE": "Root",
"es_PY": "Root",
"es_SV": "Root",
"es_UY": "Root",
"es_VE": "Root"
}
},
"parent_global_id": null,
"active": true,
"weight": 1,
"image_url": null
},
{
"global_id": "42507fb7-a0af-4419-a079-f97e4ad4f7e7",
"details": {
"name": {
"es_UY": "test"
},
"description": {
"es_UY": "tes"
}
},
"parent_global_id": null,
"active": true,
"weight": 1,
"image_url": null
}
]
}
La respuesta consiste en una lista de categorías de la tienda. Como se ve en el ejemplo, se devuelve el categoryId que luego es id que hay que enviar a la hora de asociar un producto a una categoría.
Consideraciones de performance
No exportes el catálogo completo más de 4 veces por día.
Homologación
Para dejar tu integración lista y activa en todas tus tiendas operativas, debes realizar una homologación.
Para ello, coordina aquí una reunión con el equipo de Soporte de Integraciones para certificar el correcto funcionamiento de la integración una vez que la hayas implementado.
Luego de esta reunión, la integración podrá quedar live en las tiendas reales.
Preguntas frecuentes
Preguntas frecuentes
¿Debo realizar las pruebas de la integración en una tienda real?
No, las pruebas se realizarán en una tienda de pruebas que creará tu Ejecutivo de Cuentas. De esta forma, nos aseguramos de no afectar las tiendas operativas.
Luego de que la integración sea homologada, podrás impactar información en las tiendas reales.
¿Qué es una API?
¿Qué es una API?
Una API (Interfaz de Programación de Aplicaciones) es un conjunto de reglas y definiciones que permiten que diferentes aplicaciones se comuniquen entre sí. Actúa como un intermediario que permite que dos programas se comuniquen de manera efectiva. Las API definen los métodos y protocolos que las aplicaciones pueden utilizar para solicitar y enviar datos.
Los principales usos de una API incluyen:
Integración de sistemas
Permite que diferentes sistemas informáticos se comuniquen entre sí y compartan datos de manera eficiente.Desarrollo de aplicaciones
Proporciona funciones predefinidas que los desarrolladores pueden utilizar para crear nuevas aplicaciones de forma más rápida y sencilla.Acceso a servicios web
Muchos servicios en línea, como redes sociales, servicios de pago y plataformas de almacenamiento en la nube, ofrecen API que permiten a los desarrolladores integrar estos servicios en sus propias aplicaciones.Automatización
Puedes utilizarla para automatizar tareas repetitivas o complejas, lo que ayuda a mejorar la eficiencia y reducir los errores humanos.
Personalización
Puedes personalizar la funcionalidad de una aplicación según las necesidades específicas de un usuario o empresa.
¿Qué es un webhook?
¿Qué es un webhook?
Un webhook es un mecanismo de comunicación automatizado que permite a una aplicación enviar información en tiempo real a otra aplicación o servicio cuando ocurre un evento específico. En lugar de que una aplicación solicite datos de forma periódica, el webhook permite que la aplicación receptora sea notificada de inmediato cuando hay nuevos datos disponibles o cuando se produce un evento relevante.
Los webhooks son útiles como notificaciones de cambios en bases de datos, actualizaciones de estado en sistemas de seguimiento, integraciones entre aplicaciones, entre otros casos de uso. Por ejemplo, un servicio de pagos en línea puede utilizar un webhook para notificar a una tienda en línea cuando se ha completado un pago, lo que desencadenaría acciones como actualizar el inventario o enviar un correo electrónico de confirmación al cliente.
¿Es necesario configurar un Webhook?
¿Es necesario configurar un Webhook?
Sí, deben contar con un Webhook ya que algunos de los endpoints de la API trabajan de forma asíncrona y a través de el recibirán el resultado del procesamiento de sus peticiones.
¿Qué es un cURL?
¿Qué es un cURL?
cURL es una herramienta de línea de comandos que se utiliza para transferir datos a través de varios protocolos, como HTTP, HTTPS, FTP, FTPS, SCP, SFTP, LDAP y otros. Su nombre completo es "Client for URLs" (Cliente para URLs), lo que refleja su capacidad para trabajar con diversas URL y protocolos de red.
Es una herramienta versátil que permite interactuar con servidores web y transferir datos de manera eficiente a través de una variedad de protocolos de red. Es útil para una amplia gama de tareas relacionadas con la transferencia de datos y la comunicación en línea.
Algunos de los posibles usos de cURL incluyen:
Transferencia de archivos
Puedes utilizarla para descargar o subir archivos a través de FTP, FTPS, SCP o SFTP.
Interacción con APIs
Puedes realizar solicitudes a APIs web y recibir respuestas, lo que permite probar y depurar servicios web.
Pruebas de conectividad
Puedes verificar la conectividad con servidores web y probar la disponibilidad de servicios en línea.
Descarga de contenido web
Puedes descargar páginas web completas o recursos específicos, como imágenes o archivos CSS.
Pruebas de velocidad de conexión
Puedes medir la velocidad de descarga y carga de archivos desde y hacia un servidor.
Autenticación y gestión de cookies
Puedes gestionar la autenticación con servidores web y las cookies para mantener la sesión activa.
¿Todos los usuarios del Vendor Portal tienen acceso al plugin Shops Integrations?
¿Todos los usuarios del Vendor Portal tienen acceso al plugin Shops Integrations?
No. Podrás acceder al plugin Shops Integrations solo si tu usuario tiene permisos de Admin.
¿Qué datos de mi producto puedo actualizar a través de la API?
¿Qué datos de mi producto puedo actualizar a través de la API?
A través de la API puedes actualizar los datos:
price
disponibilidad: campo active o quantity*
maximum_sales_quantity
El campo quantity sólo se puede utilizar con el endpoint bulk siempre que se actualice más de un producto a la vez.
¿Cómo informo la disponibilidad de mis productos?
¿Cómo informo la disponibilidad de mis productos?
Puedes informarla a través de los campos:
active
quantity
Ten en cuenta que el campo quantity sólo se puede utilizar con el endpoint bulk siempre que se actualice más de un producto a la vez.
¿Cómo modifico el resto de los campos de mis productos (imagen, SKU, GTIN, nombre)?
¿Cómo modifico el resto de los campos de mis productos (imagen, SKU, GTIN, nombre)?
Los cambios en estos campos (imagen, SKU, GTIN, nombre) debes gestionarlos directamente con tu Representante de cuenta.
¿El campo category_id varía entre las tiendas de una misma cadena o partner?
¿El campo category_id varía entre las tiendas de una misma cadena o partner?
Sí, este campo es único para cada tienda. Si tienes más de una tienda, este campo variará entre ellas.
¿Cómo creo productos en mi tienda que no se encuentren en el Catálogo Global de PedidosYa?
¿Cómo creo productos en mi tienda que no se encuentren en el Catálogo Global de PedidosYa?
Puedes crear estos productos y agregarlos a tu catálogo desde el Vendor Portal, o gestionarlos directamente con tu Representante de cuenta.
¿Cada cuánto debo enviar la información de actualizaciones de mi catálogo?
¿Cada cuánto debo enviar la información de actualizaciones de mi catálogo?
Para mantener tu catálogo actualizado, debes enviar los cambios puntuales ante faltante de disponibilidad o reposición de productos en tiempo real. Del mismo modo, debes enviar una actualización diaria de todo el catálogo para optimizar cualquier diferencia o actualizar precios (fuera del horario operativo).
Contacto
Si tienes alguna duda o consulta durante el proceso de integración, contacta a nuestro equipo de Soporte de Integraciones vía e-mail soporteintegraciones@pedidosya.com
Y si surge cualquier inconveniente después de que la integración esté activa, contacta a tu Representante de cuenta o reporta el issue aquí.
Page updated
Report abuse