Última actualización 15/03/2023

Flete dinámico

Importante:
Esta funcionalidad solo está disponible para integradores certificados. Para obtener la aprobación del desarrollo, debes contactar a tu Partner Development.

Flete dinámico tiene el objetivo de agilizar la selección de precios y plazos de flete para los vendedores con Mercado Envíos 1, y mejorar la experiencia del comprador brindándole información más precisa de los plazos del flete aplicados por cada vendedor. También, amplía el catálogo de los vendedores que cuentan con más de un centro de distribución generando un aumento en las ventas. Mira nuestro webinar con las últimas actualizaciones:



Dinámica de integración

Para integrar esta funcionalidad debes disponibilizar un endpoint, en el cual Mercado Libre realizará una llamada para obtener la información del flete que se muestra en la plataforma al momento de la compra.


Tiempo de respuesta

El tiempo de respuesta del endpoint no puede superar los 400 ms. Antes de activar el endpoint, habrá varias validaciones, entre ellas, la validación de carga para evaluar el tiempo de respuesta y el resultado será compartido con el integrador. En caso de superar el tiempo límite, la integración no será aprobada y no podrá ser activada para los vendedores.

Nota:
La actual infraestructura de flete dinámico está ubicada en la región este de EE.UU. (Virginia).

Contingencia

En los casos de falla en la cotización y para que el comprador no quede sin una respuesta, utilizamos como contingencia la calculadora MELI. En esta herramienta interna el vendedor carga sus tarifarios con el apoyo del asesor comercial.
La contingencia se activará en las siguientes situaciones:

  • Errores/falta de disponibilidad del integrador.
  • Tasa de timeouts muy alta (en caso de superar los 400 ms).
  • Cuando se devuelva -1 o 1 al error_code en la respuesta.

Contrato de la API

Para la creación del endpoint, deben seguirse las reglas del contrato, como se indica a continuación:

  • El nombre del endpoint estará a cargo del integrador, y solo bastará respetar el “contrato” estipulado para los request y responses.
  • En el request se encuentra apenas un ítem de un vendedor.

A continuación, se presenta la descripción de cada uno de los ítems admitidos en el payload:

destination (object)​: obligatorio. Es la información de la dirección donde el producto va ser entregado.

  • Para Brasil, Argentina y México será informado el código postal.
  • Para Chile, región/comuna, separado por "/".
  • Para Colombia, departamento/ciudad.
  • Para Uruguay, departamento/localidad.
  • Para Perú, departamento/provincia.

buyer_id (int): opcional. Es el identificador del usuario que está comprando en Mercado Libre. Solo está disponible cuando el usuario que realiza la cotización está logueado en la plataforma Mercado Libre.
seller_id (int)​​: obligatorio. Es la identificación de la cuenta dentro de Mercado Libre.
declared_value (float)​​: opcional. Es el valor que va ser declarado en la factura.
id (string): obligatorio. Es la identificación del ítem registrado en Mercado Libre.
variation_id (long): obligatorio. Es la identificación de la variante elegida por el comprador para la compra, tiene dato solo cuando la cotización corresponde a un item con variación.
category_id (string)​​: opcional. Es la identificación de la categoría del ítem dentro de Mercado Libre.
store_id (int)​​: opcional. Es la identificación de la tienda oficial dentro de Mercado Libre.
SKU (string)​​: obligatorio. Es la identificación del producto al ser comprado.
quantity (int)​​: obligatorio. Es la cantidad que será comprada de un mismo ítem.
origin (object)​​: opcional. Es el Código Postal registrado por el vendedor.
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.
dimensions (object)​​: obligatorio. Es la lista de medidas de un producto.

  • length (int)​​: obligatorio. Es el largo del producto (en centímetros).
  • width (int)​​: obligatorio. Es el ancho del producto (en centímetros).
  • height (int)​​: obligatorio. Es el alto del producto (en centímetros).
  • weight (int)​​: obligatorio. Es el peso del producto (en gramos).
Importante:
Cuando la cantidad de ítems es mayor a 1, hay un algoritmo en el marketplace que consolida los volúmenes en la mejor combinación de dimensiones, para optimizar el espacio. En este caso, la integración debe considerar siempre los valores enviados en el request y no hacer ninguna multiplicación.

Ejemplo zip_code:

{
   "seller_id": 123333,
   "buyer_id": 432123,
   "declared_value": 95.99,
   "items": [
       {
           "id": "MLB1223500643",
           "variation_id": 3123212,
           "category_id": "MLB1234",
           "price": 15.5,
           "quantity": 1,
           "SKU": "ITXEV8URJCPUN0UP",
           "store_id": 231,
           "dimensions": {
               "height": 10,
               "width": 10,
               "length": 15,
               "weight": 500
           }
       }
   ],
   "destination": {
       "type": "zipcode",
       "value": "88063038"
   },
   "origin": {
       "type": "zipcode",
       "value": "88063038"
   }
}

Ejemplo city:

{
   "seller_id": 123333,
   "buyer_id": 432123,
   "declared_value": 95.99,
   "items": [
       {
           "id": "MLB1223500643",
           "variation_id": 3123212,
           "category_id": "MLB1234",
           "price": 15.5,
           "quantity": 1,
           "SKU": "ITXEV8URJCPUN0UP",
           "store_id": 231,
           "dimensions": {
               "height": 10,
               "width": 10,
               "length": 15,
               "weight": 500
           }
       }
   ],
 "destination": {
		"type": "city",
		"value": "Ñuble/Yungay"
	},
	"origin": {
		"type": "city",
		"value": "Metropolitana/Pudahuel"
   }
}
Notas:
- La respuesta debe tener la cotización correspondiente al ítem comprado.
- Podrán ser enviadas varias cotizaciones, teniendo todas la distinción de plazo/promesa de entrega y precio.
- Todos los valores de respuesta son obligatorios.

A continuación, se presenta la descripción de cada uno de los ítems admitidos en el payload:

packages (array)​​: Es la lista de paquetes creada por el vendedor.
dimensions (object)​​: obligatorio. Es la lista de medidas de un producto.
items (array)​​: Es la lista de ítems dentro de un mismo paquete.
dimensions (object)​​: obligatorio. Es la lista de medidas de un producto.
id (string): obligatorio. Es la identificación del item registrado en Mercado Libre.
variation_id (long): obligatorio. Es la identificación de la variante elegida por el comprador.

  • quantity (int)​​: Es la cantidad del producto que se enviará
  • error_code (int)​​: Es el código que identificará el tipo de error relacionado con el producto. La lista de los códigos admitidos será presentada en las siguientes secciones.
  • quotations (array)​​: Son las informaciones del flete para un ítem.

    • price (float)​​: Es el precio del flete que será presentado al comprador.
    • 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.
    • 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).
    • promise (int)​​: Es la suma de los valores de handling_time y shipping_time.
    • service (int) : Es el código que identifica un servicio/carrier dentro del contexto del vendedor. Los valores válidos van de 0 a 99. Este código es único e de responsabilidad exclusivo del vendedor/integrador, siendo responsabilidad de Mercado Libre solo pasar este valor.
    Importante:
    En caso de ser enviado solo un dígito, será completado automáticamente con 0 a la izquierda. Y en caso de enviar más de 2 dígitos, la información no será integrada y devolverá 00 en el código del carrier.

    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
                }
             ]
          }
       ]
    }

    En caso de haber algún error interno o algún ítem esté asociado a un error, la estructura de la respuesta deberá ser como la siguiente. Para el error code 3 (sin cobertura), el HTTP Status debe ser 400 (bad request) y para cualquier otro error code u error interno asociado a la cotización, debe ser 500 (internal server error).


    Respuesta:

    {
       "message": "any message",
       "error_code": 1
    }

    Usar caché

    Para la adopción del caché de las respuestas, será utilizado la RFC IETF 7234 (ver más). Esta RFC fue definida por la comunidad y reúne las mejores prácticas de caché de llamadas HTTP.


    Verbo HTTP

    Para la implementación de la misma, será cambiado el verbo HTTP de los endpoints de cotización de envíos del POST para GET. Esto será necesario para que la semántica de los sea adecuada al protocolo HTTP, en la cual, está sugerido que solo las llamadas GET deban ser cacheadas.


    Headers

    Además, será adicionado el header en las llamadas y respuestas de las llamadas a los partners.
    Para las llamadas serán adicionados a los headers:

    Atributo Valor
    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.

    A su vez, para las respuestas de los integradores, será necesario sumar los headers:

    Atributo Valor
    Cache-Control Utilizado para especificar las directivas para el caché de las respuestas. Las directivas que debes adaptar son:
    1. no-store: (opcional) indica que la respuesta no debe ser cacheada. Se utiliza esta directiva, las demás no son necesarias;
    2. must-revalidate: debes verficar si la respuesta es válida con el integrador. Este debe devolver el HTTP Status 304 si aún fuera válida 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é.
    3. private: (obligatorio) la respuesta no debe ser almacenada por cualquier proxy intermediario.
    4. 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álido. 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.

    Contrato de la respuesta

    Sumaremos un nuevo atributo destinations en la respuesta de las llamadas y debe contener todos los destinos que la cotización puede ser utilizada. Este atributo será una lista de strings y puede contener solo el destino para la cual la cotización fue solicitada. Con eso, con una única cotización, puedes evitar N otras llamadas.
    El cuadro de abajo presenta un ejemplo de respuesta donde es verificado el header ETag devuelto que la respuesta cacheada aún es 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

    Finalmente, la siguiente tabla presenta una respuesta de ejemplo donde el partner indica que la cita no debe almacenarse en caché. Debe contener la directiva no-store en el header Cache-Control.

    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


    Errores

    Importante:
    El error code 1 direcciona la cotización para contingencia.

    Conoce los errores validos:

    Parámetro Descripción
    -1 Error interno en la aplicación del integrador y el comprador va a recibir la cotización de la calculadora MELI (contingencia).
    2 CP de destino inválido.
    3 Producto no disponible para el Código Postal de destino.

    Siguiente: Mercado Envíos 2.