Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Flete Dinámico
Flete Dinámico es una funcionalidad de Mercado Envíos 1 que agiliza la selección de precios y plazos de envío para vendedores y brinda a los compradores información precisa sobre los plazos de entrega. Esta configuración verifica en tiempo real los precios y condiciones de envío, y muestra el costo del envío antes de la compra, mejorando la experiencia y la eficiencia logística. Asimismo, para poder registrar correctamente el desarrollo de esta funcionalidad es necesario incurrir en un proceso de homologación.
Dinámica de Homologación
La homologación es un proceso en el que Mercado Libre verifica y aprueba una URL externa para que los usuarios puedan registrarse en Mercado Libre desde ese sitio de manera segura y confiable. Ello implica pruebas técnicas, evaluación de seguridad y la implementación de medidas necesarias para garantizar la autenticidad y protección de los datos de los usuarios. Una vez aprobada, la URL se convierte en un canal válido para los usuarios de ME1.
Requisitos de Homologación
A continuación se presentan los requisitos de homologación para garantizar una integración exitosa con nuestra plataforma de flete dinámico:
- Cumplimiento del Contrato
- Tiempo de Respuesta Óptimo
- Ubicación de Infraestructura
- Especificaciones del Origen y Destino de Datos
- Uso de Caché
- Monitoreo de errores
- Contingencia Mercado Libre
- La URL no tiene una estructura específica, lo que brinda flexibilidad en la configuración.
- Cada request debe contener únicamente un ítem de un vendedor. Esto es fundamental para mantener la eficiencia en la transmisión de datos.
- Utiliza el método HTTP GET para acceder al endpoint. Este método es adecuado para solicitar datos y es comúnmente utilizado en integraciones web.
- Detalla claramente la fuente de datos (origen) y el sistema de destino. Comprender estos aspectos es fundamental para garantizar un flujo de datos sin problemas y preciso.
- Familiarízate con la necesidad de mantener el tiempo de respuesta por debajo de los 400 ms y comprende su importancia para una integración exitosa.
- Antes de activar el endpoint, somételo a una validación de carga inicial. Esto implica evaluar su tiempo de respuesta bajo condiciones normales de uso.
- Si el tiempo de respuesta supera el límite, se requieren acciones correctivas. Esto puede incluir la revisión y optimización del código y la infraestructura.
- Si el tiempo de respuesta cumple con el requisito de 400 ms, la integración es aprobada y puede ser activada para los vendedores.
- Asegúrate de seguir optimizando el tiempo de respuesta de forma continua para brindar una experiencia de usuario excepcional.
- Considera que la actual infraestructura de flete dinámico se encuentra en la región este de EE.UU., específicamente en Virginia.
- Evalúa si es necesario optimizar tu aplicación o ajustar la configuración para aprovechar al máximo la ubicación de la infraestructura.
Cumplimiento del Contrato
A continuación, te presentamos un enfoque paso a paso al crear el endpoint para la homologación:
Tiempo de Respuesta Óptimo
Este enfoque es esencial para garantizar una experiencia de usuario eficiente y evitar problemas de integración con los vendedores, para ello:
Ubicación de Infraestructura
Siguiendo estos pasos, podrás tomar decisiones informadas para mejorar el rendimiento de tu aplicación en función de la ubicación de la infraestructura:
Origen y Destino de Datos
Especificaciones de la fuente de datos (origen)
Las especificaciones de la fuente de datos forman parte del protocolo de comunicación o intercambio de datos en el proceso de homologación:
Ejemplo por Zip_Code:
{
"seller_id": 337352780,
"buyer_id": 3123212,
"declared_value": 69.9,
"items": [
{
"id": "MLB1223500643",
"variation_id": 0,
"category_id": "ABC1234",
"price": 69.9,
"quantity": 1,
"sku": "RB-PC890A",
"store_id": 231,
"dimensions": {
"height": 10,
"width": 10,
"length": 31,
"weight": 500
}
}
],
"destination": {
"type": "zipcode",
"value": "88063038"
},
"origin": {
"type": "zipcode",
"value": "88063038"
}
}Ejemplo por City:
{
"seller_id": 337352780,
"buyer_id": 3123212,
"declared_value": 69.9,
"items": [
{
"id": "MLB1223500643",
"variation_id": 0,
"category_id": "ABC1234",
"price": 69.9,
"quantity": 1,
"sku": "RB-PC890A",
"store_id": 231,
"dimensions": {
"height": 10,
"width": 10,
"length": 31,
"weight": 500
}
}
],
"destination": {
"type": "city",
"value": "Ñuble/Yungay"
},
"origin": {
"type": "city",
"value": "Metropolitana/Pudahuel"
}
}Parámetros de respuesta:
seller_id (string): Obligatorio. Es la identificación de la cuenta dentro de Mercado Libre.
buyer_id (string): Opcional. Es el identificador del usuario que está comprando en Mercado Libre. Solo está disponible cuando el usuario que realiza la está logueado en la plataforma Mercado Libre.
declared_value (float): Opcional. Es el valor que va ser declarado en la factura.
items (array): obligatorio. Información del ítem comprado.
- items.id (string): Obligatorio. Es la identificación del producto registrado en Mercado Libre.
- items.variation_id (string): Obligatorio. Es la identificación de la variante elegida por el buyer para la compra, tiene dato solo cuando la cotización corresponde a un ítem con variación.
- items.category_id (string): Opcional. Es la identificación de la categoría del producto dentro de Mercado Libre.
- items.price (float): Opcional. Es el precio unitario del producto multiplicado por la cantidad de ítems elegidos por el comprador, al momento de la cotización.
- items.quantity (int): Obligatorio. Es la cantidad que será comprada de un mismo producto.
- items.sku (string): Obligatorio. Es la identificación del producto al ser comprado.
- items.store_id (string): Opcional. Es la identificación de la tienda oficial dentro de Mercado Libre.
- items.dimensions (object): Obligatorio. Es la lista de medidas de un producto.
- items.dimensions.length (float): Obligatorio. Es el largo del producto (en centímetros).
- items.dimensions.width (float): Obligatorio. Es el ancho del producto (en centímetros).
- items.dimensions.height (float): Obligatorio. Es el alto del producto (en centímetros).
- items.dimensions.weight (float): Obligatorio. Es el peso del producto (en gramos).
origin (object): Opcional. Es la información de la dirección de origen de la entrega o del vendedor.
destination (object): )bligatorio. Es la información de la dirección donde el producto va ser entregado. A continuación, el detalle de acuerdo a cada país:
| País | Detalle |
|---|---|
| Brasil | Código Postal |
| Argentina | Código Postal |
| México | Código Postal |
| Chile | Región / Comuna |
| Colombia | Departamento / Localidad |
| Perú | Departamento / Provincia o Distrito |
| Uruguay | Departamento / Localidad |
Especificaciones del destino de los datos (destino)
Las especificaciones del destino de datos forman parte del protocolo de comunicación o intercambio de datos en el proceso de homologación:
Ejemplo:
{
"destinations":[
"88063038"
],
"packages":[
{
"dimensions":{
"height":10,
"width":10,
"length":15,
"weight":500
},
"items":[
{
"id":"MLB1223500643",
"variation_id":3123212,
"quantity":1,
"dimensions":{
"height":10,
"width":10,
"length":15,
"weight":500
}
}
],
"quotations":[
{
"price":119.88,
"handling_time":0,
"shipping_time":4,
"promise":4,
"service":99
},
{
"price":0,
"handling_time":0,
"shipping_time":6,
"promise":6,
"service":99
}
]
}
]
}Parámetros de respuesta:
destinations (array): Información que contiene códigos postales u otras identificaciones de destinos a los que se enviarán los paquetes.
packages (array): Información que representa los paquetes creados por el vendedor.
- packages.dimensions (object): Obligatorio. Es la lista de medidas del paquete. items (array): obligatorio. Información del ítem comprado.
- items.id (string): obligatorio. Es la identificación del ítem registrado en Mercado Libre.
- items.variation_id (string): Obligatorio. Es la identificación de la variante elegida por el comprador.
- items.quantity (int): Es la cantidad del producto que se enviará.
- items.dimensions (object): Obligatorio. Es la lista de medidas del ítem. quotations (array): obligatorio. Información del flete para un producto.
- quotations.price (float): Es el precio del flete que será presentado al comprador.
- quotations.handling_time (int): Es el tiempo, en días hábiles, que se utilizará para separar y embalar el producto. Abarca todos los procesos previos al envío efectivo del paquete. En el caso de que esa información no esté disponible, debe devolverse el valor 0.
- quotations.shipping_time (int): Es el tiempo, en días hábiles, de tránsito del paquete (desde la entrada al camión hasta la entrega al comprador).
- quotations.promise (int): Es la suma de los valores de handling_time y shipping_time.
- quotations.service (int) : Es el código del servicio/carrier con identificación única que va de 0 a 99, asignada por el vendedor/integrador.
- Para el código de error 3 (sin cobertura), el estado HTTP debe ser 400 (Solicitud incorrecta).
- Para cualquier otro código de error o error interno relacionado con la cotización, el estado HTTP debe ser 500 (Error interno del servidor).
En el caso de que se produzca un error interno o que un ítem esté relacionado con un error, la estructura de la respuesta debe seguir el siguiente formato:
Ejemplo de Respuesta:
{
"message": "any message",
"error_code": 1
}Uso de Caché
En este contexto, será utilizado la RFC IETF 7234, una especificación ampliamente reconocida que establece las mejores prácticas para el almacenamiento en caché de llamadas HTTP.
Verbo HTTP
En este contexto, es esencial alinear la semántica de nuestras llamadas con el protocolo HTTP, que sugiere que solo las llamadas GET deben ser cacheadas.
Headers
Se deben incorporar encabezados adicionales en las llamadas y respuestas realizadas a integradores. En el caso de las llamadas, se deben agregar los siguientes encabezados:
| Atributo | Descripción |
|---|---|
| If-None-Match | Identificador del recurso (cotización) en cuestión (header ETag). Es utilizada para verificar si la versión del recurso aún es válida. Es válido si el partner devuelve el HTTP status 304 sin contenido. En caso contrario, devuelve una nueva versión del recurso y una nueva ETag. |
Por otro lado, en las respuestas proporcionadas de los integradores, es necesario incluir los siguientes encabezados adicionales:
| Atributo | Descripción |
|---|---|
| Cache-Control | Utilizado para especificar las directivas para el caché de las respuestas. Las directivas que debes adaptar son:
|
| Age | Tiempo en segundos desde que la versión del recurso pasó a ser válida. En caso de no existir este control por parte de los partners, debes enviar el valor cero (0). |
| ETag | Identificador de la versión del recurso. Es obligatorio utilizarlo. |
En busca de optimizar nuestras respuestas y reducir el número de llamadas, el atributo llamado destinations contendrá una lista de destinos en forma de strings, indicando todos los lugares donde se puede utilizar la cotización. Ahora, con una sola cotización se pueden evitar realizar múltiples llamadas, mejorando significativamente la eficiencia de nuestras API.
A continuación, presentamos un ejemplo de cómo se puede verificar el header ETag devuelto para determinar si la respuesta cacheada sigue siendo válida. Ejemplo de llamada con validación caché:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:private;max-age:1000000 - Age:50000 - ETag:0943dc18-a8d7-4508-97a9-ba9221fa |
304 | No Content |
Para brindar un control más granular sobre el almacenamiento en caché, estamos introduciendo la directiva no-store en el header Cache-Control de nuestras respuestas. Esta directiva permite a los partners indicar que una cita no debe almacenarse en caché.
Ejemplo de respuesta sin permitir el caché:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:no-store | 200 | Igual body de la respuesta de la cotización |
Ejemplo de respuesta con caché:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:private;max-age:1000000 - Age:0 - ETag:0943dc18-a8d7-4508-97a9-ba9221fa |
200 | Igual body de la respuesta de la cotización |
Monitoreo de errores
A continuación, enumeramos los posibles errores en relación al manejo de Flete Dinámico:
| Parámetro | Descripción | Posible Solución |
|---|---|---|
| -1 | Este error se produce cuando la aplicación del integrador experimenta problemas internos que impiden su funcionamiento adecuado. Como resultado, el comprador recibirá una cotización de la calculadora MELI en modo de contingencia. | En caso de un error interno en la aplicación del integrador, se recomienda tener en cuenta la Tabla de Contingencia como un plan de respaldo. Cuando se detecta un error interno, la aplicación activa automáticamente la consulta a la Tabla de Contingencia. |
| 1 | Este error ocurre cuando el producto seleccionado por el comprador no está disponible en el inventario. Como resultado, no es posible calcular una cotización de envío para un producto que no se encuentra en stock. | Se recomienda implementar un proceso de gestión de inventario efectivo o considerar mostrar alternativas de productos similares disponibles. |
| 2 | Este error ocurre cuando el destino (código postal, comuna, etc) proporcionado por el comprador no es válido. Como resultado, no se puede calcular una cotización de envío precisa. | Al verificar el destino como inválido, la aplicación debe consultar la Tabla de Contingencia. Si la Tabla de Contingencia contiene información válida para el destino ingresado, esta información debe utilizarse para calcular la cotización de envío. |
| 3 | Este error se produce cuando el producto seleccionado por el comprador no está disponible para su entrega en el destino especificado. Como resultado, no se puede calcular una cotización de envío. | Si el producto no está disponible en la ubicación original, la Tabla de Contingencia podría contener información sobre productos alternativos o ubicaciones de entrega alternativas. |
| 4 | Este error se produce cuando la aplicación no puede encontrar el producto especificado por el comprador. Esto impide calcular una cotización de envío precisa. | Asegurar que la base de datos de productos esté actualizada y sea fácilmente accesible para la aplicación. |
Contingencia Mercado Libre
La Tabla de Contingencia, también conocida como Tabla Axado, se trata de una plantilla de transportadoras que se puede cargar directamente desde Mercado Libre. Su función principal es actuar como un plan de respaldo en caso de que el endpoint o URL del integrador falle. En otras palabras, es una herramienta de seguridad diseñada para mantener la operación de los vendedores en marcha incluso cuando surgen problemas inesperados.
A continuación, algunos criterios a tener en cuenta:
- Requerimiento Inicial: El Asesor Comercial de MELI solicitará al vendedor la Tabla de Contingencia al activar la integración con el integrador de flete dinámico.
- Responsabilidad del Vendedor: El vendedor debe completar y mantener actualizada esta tabla con los valores tanto en el integrador como en MELI.
- Establecer Reglas de Flete: Se recomienda que el vendedor establezca reglas claras de flete, como costos cero para ubicaciones cercanas, para optimizar la entrega.
- Actualización Fácil: Si el vendedor desea actualizar la tabla, puede hacerlo desde MELI ubicándolo desde Mi Perfil -> Ventas -> Preferencias de Ventas -> Transportadoras.
Además, adjuntamos un desglose por país junto con un enlace de referencia a la Tabla de Contingencia Modelo:
| País | Detalle | Link |
|---|---|---|
| Brasil | Código Postal | https://www.mercadolivre.com.br/transportadoras/config |
| Argentina | Código Postal | https://www.mercadolibre.com.ar/transportadoras/config |
| México | Código Postal | https://www.mercadolibre.com.mx/transportadoras/config |
| Chile | Región / Comuna | https://www.mercadolibre.cl/transportadoras/config |
| Colombia | Departamento / Localidad | https://www.mercadolibre.com.co/transportadoras/config |
| Perú | Departamento / Provincia o Distrito | https://www.mercadolibre.com.pe/transportadoras/config |
| Uruguay | Departamento / Localidad | https://www.mercadolibre.com.uy/transportadoras/config |