Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 27/09/2024

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

Cumplimiento del Contrato

A continuación, te presentamos un enfoque paso a paso al crear el endpoint para la homologación:

  • 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.
Importante:
Reúne los siguientes elementos necesarios:
  • URL o endpoint que deseas registrar.
  • Headers requeridos para la comunicación.
  • Formato de body o JSON request que cumpla con las especificaciones.
  • Nombre y ID de tu aplicación.

Considera crear un video corto que muestre el desarrollo realizado para validar y verificar las especificaciones del contrato. Esto puede ser útil para documentar el proceso y compartir sugerencias. Para la creación de la aplicación, te sugerimos revisar la documentación: Registra tu aplicación

Es importante destacar que el proceso de homologación está reservado exclusivamente para integradores certificados. Si perteneces a este grupo, te invitamos a generar un ticket para iniciar el proceso de homologación. En caso de que aún no estés certificado, te recomendamos verificar nuestro Developer Partner Program para obtener más información sobre cómo obtener tu certificació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:

  • 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.

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:

  • 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.

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 (int)​​: Obligatorio. Es el largo del producto (en centímetros).
      • items.dimensions.width (int)​​: Obligatorio. Es el ancho del producto (en centímetros).
      • items.dimensions.height (int)​​: Obligatorio. Es el alto del producto (en centímetros).
      • items.dimensions.weight (int)​​: 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


Nota:
  • Cuando la cantidad de ítems sea mayor a 1, Mercado Libre utilizará un algoritmo para consolidar las dimensiones en la mejor combinación posible para optimizar el espacio. En este caso, la integración debe usar los valores enviados en el request sin realizar ninguna multiplicación.
  • La respuesta debe incluir la cotización correspondiente al ítem comprado.
  • Es posible enviar varias cotizaciones, cada una con distinto plazo/promesa de entrega y precio.
  • Todos los valores de respuesta son obligatorios y deben ser proporcionados.


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.
Nota:
En el caso del atributo quotations.service:
  • Este código es de responsabilidad exclusiva del vendedor/integrador, Mercado Libre solo lo transmite.
  • Este código se utilizará posteriormente en el shipping del pedido, en el campo option_id para identificar a la transportadora.
  • El ID estará en la tercera y cuarta posición del ID generado en este campo.
    • Por ejemplo, si el ID de option_id es 112233445566, el ID del transportista, en este caso, es 22, que debe coincidir con el valor enviado en la cotización en el campo quotations.service.
    • Recuerda consultar el recurso de envío utilizando el encabezado x-format-new=true según la documentación.
  • Si envías solo un dígito, se completará automáticamente con un 0 a la izquierda. Por ejemplo, si envías 5, se convertirá en 05.
  • En caso de enviar más de 2 dígitos, la información no será integrada y el código del carrier retornará "00". Por ejemplo, si envías 123, la respuesta será 00.
  • Es fundamental incluir al menos un objeto dentro del array quotations.

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:

  • 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).

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:
  • no-store: (opcional) indica que la respuesta no debe ser cacheada. Se utiliza esta directiva, las demás no son necesarias.
  • must-revalidate: Debes verificar si la respuesta es válida con el integrador. Este debe devolver el HTTP Status 304 si aún fuera válido o 200 con el nuevo valor para la cotización. Esta validación es opcional y queda a criterio del integrador adoptarla o no. Si no la adaptas, será utilizado el max-age para definir el TTL de la respuesta en el caché.
  • private: (obligatorio) la respuesta no debe ser almacenada por cualquier proxy intermediario.
  • max-age: (obligatorio) tiempo máximo en segundos que la respuesta es válida.
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
Importante:
Para evitar errores al cargar la Tabla de Contingencia, es importante seguir estas recomendaciones:
  • Tener en cuenta que las transportadoras registradas en Mercado Libre siguen el esquema de códigos 16 para vendedores de Brasil y 17 para los demás países, según lo establecido en la Tabla de Contingencia.
  • Verificar extensión del archivo: Asegurar que el archivo tenga la extensión correcta según el modelo de Mercado Libre.
  • Mantener los nombres de las hojas: No modificar los nombres de las hojas en la plantilla a cargar. Todo debe coincidir con el modelo original. Además, no se debe eliminar ninguna hoja.
  • Conservar encabezados: No cambiar los encabezados en el archivo. Verificar que la estructura de la hoja de trabajo se mantenga de acuerdo con el modelo.
  • Validar información: Verificar que los códigos postales sean correctos. Prestar atención a las mayúsculas y minúsculas cuando se refiera a departamentos, ciudades, comunidades, etc.