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.

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:

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.

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:

Por otro lado, en las respuestas proporcionadas de los integradores, es necesario incluir los siguientes encabezados adicionales:

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é:

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é:

Ejemplo de respuesta con caché:

Monitoreo de errores

A continuación, enumeramos los posibles errores en relación al manejo de Flete Dinámico:

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: