Documentación Mercado Envíos

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

Documentación

Última actualización 08/07/2024

Envíos Turbo

Importante:
Actualmente, este tipo de logisitica se encuentra disponible solo para vendedores de Argentina - AMBA.
A partir del 15 de Julio estará también disponíble para vendedores de Brasil - São Paulo

Envíos Turbo es un servicio de entregas que se enfoca en proporcionar envíos rápidos en menos de 3 horas. Está diseñado para atender en un radio cercano al vendedor y se basa en el modelo logístico de Flex. Este servicio tiene como objetivo ofrecer una opción de entrega extremadamente rápida, lo que puede ser especialmente útil para brindar un servicio de alta calidad a los usuarios.

Encuentra más información relacionada con Turbo en los siguientes enlaces:


Nota:
- Es fundamental respetar el límite de 1000 rpm en todas las llamadas a los recursos de Flex y Turbo, dado que es compartido entre estos 2 tipos de envío. Mantener este límite garantiza un uso eficiente y equitativo de los recursos disponibles.
- La app de envíos Flex de Mercado Libre es necesaria para escanear las entregas y hacer los recorridos de entregas. Sin embargo, no está disponible para integraciones, por lo que las empresas logísticas deberán adaptarse.

Áreas de cobertura por países

Para poder ofrecer Envíos Turbo, la dirección de envío del vendedor debe estar habilitada para alguna de las áreas de cobertura según el país:

País Cobertura
Argentina AMBA (Área Metropolitana de Buenos Aires)
Brasil São Paulo

Configurar un usuario de test

Para configurar la funcionalidad de Envíos Turbo para usuarios de prueba, tomar en cuenta:


1. Inicie sesión en la cuenta en la que desea habilitar Envío Turbo.
2. Valide que el usuario ya tenga activo Envíos Flex dado que es un requisito previo.
3. Asegúrese de que la cuenta tenga publicaciones activas en ME2.
4. Verifique que su cuenta tenga una reputación Amarilla o Verde.
5. Asegúrese de tener una dirección de correo compatible con el área de cobertura de su país.
6. Configure la dirección de envío en AMBA.
7. Active Envíos Turbo a la cuenta, dirigiéndose a “Mi Perfil” > “Ventas” > “Preferencias de Venta”.
8. Una vez que haya completado estos pasos, debería poder utilizar Envíos Turbo como usuario de prueba.

Consultar suscripciones de un usuario

Este endpoint permite consultar las suscripciones que tiene un usuario.

  • Si el usuario activa ambos servicios, Flex y Turbo, tendrá dos suscripciones, ya que Flex es un requisito para acceder a Turbo.


Nota:
En el contexto de las suscripciones, cada una de ellas cuenta con un identificador único llamado service_id. Este identificador es fundamental para poder acceder a la configuración de la suscripción y realizar cambios en ella. Para este caso, el que se utilizará será el service_id de la modalidad Turbo.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/subscriptions/v1

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/subscriptions/v1

Respuesta:

[
    {
        "id": 111181,
        "site_id": "MLA",
        "user_id": 1438865529,
        "mode": "FLEX",
        "configuration_type": {
        	"coverage": "zone",
        	"delivery": "custom"
        },       
        "service_id": 736230,
        "status": {
            "id": "in",
        },
        "creation_date": "2023-08-02T06:34:40Z"
    },
    {
        "id": 111183,
        "site_id": "MLA",
        "user_id": 1438865529,
        "mode": "TURBO",
        "configuration_type": {
        	"coverage": "radius",
        	"delivery": "accurate" 
        },  
        "service_id": 738216,
        "status": {
            "id": "in",
        },
        "creation_date": "2023-08-02T06:35:30Z"
    }
]

Parámetros de respuesta:

  • id ID único de la suscripción.
  • site_id Identificador del país.
  • user_id ID del usuario.
  • mode Tipo de suscripción (TURBO en este caso).
  • configuration_type Tipo de configuración de la suscripción (TURBO en este caso).
  • configuration_type.coverage Tipo de cobertura.
  • configuration_type.delivery Tipo de entrega.
  • service_id ID del servicio asociado a la suscripción.
  • status Estado de la suscripción.
  • status.id: Tipos de estados de la suscripción:
    • in: La suscripción está activa. En este estado el usuario puede cambiar su configuración y recibirá pedidos de envíos para el modo de suscripción.
    • out: La suscripción no está activa. En este estado el usuario no puede cambiar la configuración.
    • pending: La suscripción está pendiente de activación. En este estado el usuario puede cambiar su configuración aunque no va a recibir pedidos para realizar envíos.
  • creation_date Fecha de creación de la suscripción.

Códigos de estado de respuesta:

Código Mensaje Descripción Recomendación
200 - OK - Se actualizó correctamente la configuración. -
400 - Bad Request empty site id El site_id está vacío. Validar el site_id.
400 - Bad Request invalid site_id Site_id inválido. Validar si el site_id está habilitado para envíos Turbo.
400 - Bad Request can't access to resource Site_id inválido. Validar si el site_id está habilitado para envíos Turbo.
404 - Not Found user not found No existe el usuario. Validar el user_id.


Identificar órdenes Turbo

Este endpoint determina si un envío se manejará mediante el servicio Turbo, permitiendo concluir la transacción de manera efectiva.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/42469883906

Respuesta:

"tags": [
        "turbo"
    ]
Nota:
- Es importante aclarar que Turbo no es un tipo de logística en sí mismo. Esto significa que cuando estés interactuando con nuestros endpoints, el atributo logistic_type seguirá devolviendo el valor de self_service y no Turbo.
- Asimismo, se podrá encontrar esta misma diferencia en las tags de:
- https://api.mercadolibre.com/users/$USER_ID/shipping_preferences
- https://api.mercadolibre.com/orders/$ORDER_ID/shipments

Consultar la configuración de la suscripción

Este endpoint permite consultar la configuración de las suscripciones que tiene un usuario, para este caso de Turbo.


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/configuration/v3

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/configuration/v3

{
  "query": "{ configuration(user_id: 1438865529, service_id: 738216) { address { id address_line city { id name } zip_code } subscription { site_id user_id service_id status { id } creation_date training_times { original { value unit } remaining { value unit } activation_date } } delivery_window is_moderated delivery_ranges { week { capacity type processing_time from to et_hour calculated_cutoff } saturday { capacity type processing_time from to et_hour calculated_cutoff } sunday { capacity type processing_time from to et_hour calculated_cutoff } } working_days radius availables { capacity_range { from to } accurate_ranges { from to } radius_range { from to } } disabled_features } }"
}

Respuesta:


  {
      "configuration": {
          "address": {
              "address_line": "Testing Street 1450",
              "city": {
                  "id": "TUxBQlNBQTM3Mzda",
                  "name": "Saavedra"
              },
              "id": "1316123989",
              "zip_code": "1430"
          },
          "availables": {
             "capacity_range":  {
                 "from": 1,
                 "to": 5
             },
  "accurate_ranges": [
                  {
                     "from": 10
                     "to": 12
                  },
                  {
                     "from": 11
                     "to": 13
                  },
                  {
                     "from": 12
                     "to": 14
                  },
                  {
                     "from": 13
                     "to": 15
                  },
                  {
                     "from": 14
                     "to": 16
                  },
                  {
                     "from": 15
                     "to": 17
                  },
                  {
                     "from": 16
                     "to": 18
                  }
              ],
              "radius_range" {
                 "from": 1,
                 "to": 5
              }
          },
          "delivery_ranges": {
              "saturday": null,
              "sunday": null,
              "week": [
                  {
                      "calculated_cutoff": 10,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 10,
                      "processing_time": 0,
                      "to": 12,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 11,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 11,
                      "processing_time": 0,
                      "to": 13,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 12,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 12,
                      "processing_time": 0,
                      "to": 14,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 13,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 13,
                      "processing_time": 0,
                      "to": 15,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 14,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 14,
                      "processing_time": 0,
                      "to": 16,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 15,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 15,
                      "processing_time": 0,
                      "to": 17,
                      "type": "etd"
                  },
                  {
                      "calculated_cutoff": 16,
                      "capacity": 5,
                      "et_hour": null,
                      "from": 16,
                      "processing_time": 0,
                      "to": 18,
                      "type": "cpt"
                  }
              ]
          },
          "delivery_window": "same_day",
          "disabled_features": [],
          "is_moderated": false,
          "subscription": {
              "creation_date": "2023-08-02T06:35:30Z",
              "service_id": 738216,
              "site_id": "MLA",
              "status": {
                  "id": "in"
              },
              "training_times": null,
              "user_id": 1438865529
          },
          "working_days": [
              "week"
          ],
          "radius": 8000
      }
  }

Parámetros de respuesta:

  • address: información sobre la dirección del usuario.
  • availables: contiene información sobre la capacidad, cortes y rangos disponibles para el servicio.
  • availables.capacity_range: rango de valores para capacidad.
  • availables.accurate_ranges: rangos horarios de turbo disponibles (como mínimo el usuario debe seleccionar 3).
  • availables.radius_range: rango de radios disponibles en Kilómetros.
  • delivery_ranges: información sobre la capacidad, cortes y rangos disponibles para los diferentes días de la semana.
    • delivery_ranges.saturday: rangos de entrega y capacidad para los sábados (considerar que actualmente Turbo no está disponible para los sábados).
    • delivery_ranges.sunday: rangos de entrega y capacidad para los domingos (considerar que actualmente Turbo no está disponible para los domingos).
    • delivery_ranges.week: rangos de entrega y capacidad para los días de la semana.
    • delivery_window: el tipo de servicio para la entrega. El único valor posible para Turbo es “same_day” (envíos el mismo día).
    • disabled_features: características deshabilitadas para el servicio incluyendo, por ejemplo: "CUTOFF_BY_ZONE" y "CAPACITY_BY_DAY".
    • is_moderated: indica si el servicio está moderado (true/false).
    • subscription: información sobre la suscripción del usuario.
    • working_days: días laborables disponibles.
    • radius: radio de cobertura en metros. La cobertura se define por una circunferencia con centro en la dirección del seller y el radio definido.

    Códigos de Estado de respuesta:

    Código Mensaje Descripción Recomendación
    200 - OK - Se actualizó correctamente la configuración. -
    400 - Bad Request empty site id El site_id está vacío. Validar el site_id.
    400 - Bad Request invalid site_id Site_id inválido. Validar si el site_id está habilitado para envíos Turbo.
    400 - Bad Request can't access to resource Site_id inválido. Validar si el site_id está habilitado para envíos Turbo.
    400 - Bad Request invalid JSON body El JSON es inválido. Validar el esquema de query establecida.
    400 - Bad Request failed to create schema in graphql operation GraphQL inválida para el esquema definido. Validar el esquema de query establecida.
    400 - Bad Request invalid query GraphQL inválida para el esquema definido. Validar el esquema de query establecida.
    404 - Not Found subscriptions not found No existe suscripción a Envíos Turbo para la combinación de user_id y service_id enviada. Validar el user_id y service_id en el endpoint.
    404 - Not Found user not found No existe el usuario. Validar el user_id.

    Configurar Rangos Horarios de Entrega y Límite de Envíos

    A través de este endpoint, es posible configurar diferentes aspectos para Envíos Turbo como:
    - Rangos Horarios de Entrega
    - Límite de envíos



    Llamada:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/delivery/accurate/v3

    Ejemplo:

    
      curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/delivery/accurate/v3
      
      {
              "delivery_ranges": {
                  "week": [
                      {   
                          "from": 10,
                          "to": 12,
                          "capacity": 30
                      },
                      {   
                          "from": 11,
                          "to": 13,
                          "capacity": 20
                      },
                      {   
                          "from": 12,
                          "to": 14,
                          "capacity": 10
                      }
                  ]
              }
      }

    Parámetros de respuesta:

    • delivery_ranges.week: Información sobre rango de entrega y límite de envíos.
    • from: Hora de inicio del intervalo de tiempo para la entrega.
    • to: Hora de finalización del intervalo de tiempo para la entrega.
    • capacity: Capacidad de entrega para el intervalo de tiempo dado.
    Nota:
    - A diferencia de la configuración de Rangos Horarios de Entrega de Flex, los envíos Turbo tienen varios Rangos Horarios. Estos rangos de horario definen una ventana de entrega en la cual el vendedor debe realizar los envíos asociados a ventas en la hora previa.
    - Los valores de From y To que definen cada rango son fijos y deben tomarse de la respuesta del servicio que devuelve la configuración de Turbo del vendedor en el atributo configuration.accurate_ranges (no se pueden definir rangos custom).
    - Por ejemplo: si el Rango Horario es de 12:00 a 14:00, significa que para las ventas realizadas entre las 11:00 y las 12:00 el vendedor debe entregar el paquete entre las 12:00 y las 14:00, pudiendo así pasar un máximo de 3 horas entre la venta y la entrega.
    - Los Rangos Horarios de Entrega solo están disponibles de Lunes a Viernes, indican desde qué hora (from) y hasta qué hora (to) se define un Rango Horario de Entrega para Turbo.
    - Para garantizar la precisión de la información sobre la capacidad de entrega, incluso si se modifica la capacidad de un solo rango de entrega, es necesario enviar todos los rangos de entrega activos junto con su capacidad. De lo contrario, se asumirá que los rangos no enviados no están activos.
    Código Mensaje Descripción Recomendación
    200 - OK - Se actualizó correctamente la configuración. -
    400 - Bad Request invalid user_id User_id inválido. Validar el user_id (debe ser un número entero).
    400 - Bad Request invalid service_id Service_id inválido. Validar el service_id (debe ser un número entero).
    400 - Bad Request invalid JSON body El JSON es inválido. Validar el esquema de query establecida.
    404 - Not Found can't update delivery custom No se puedo realizar la actualización de configuración debido a que no existe suscripción a Envíos Turbo para la combinación de user_id y service_id enviada. Validar el user_id y service_id en el endpoint.

    Ampliar área de cobertura Turbo

    Este endpoint permite agregar más áreas de coberturas para Envíos Turbo.


    Llamada:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/coverage/radius/v3

    Ejemplo:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/coverage/radius/v3
    
    {
      "radius": 8000
    }
    Nota:
    En este ejemplo, se establece que el vendedor tiene cobertura de entrega en un radio de 8000 metros. Los radios pueden variar desde un mínimo de 1000 metros hasta un máximo de 8000 metros.

    Códigos de estado de respuesta:

    Código Mensaje Descripción Recomendación
    200 - OK - Se actualizó correctamente la configuración. -
    400 - Bad Request invalid user_id User_id inválido. Validar el user_id (debe ser un número entero).
    400 - Bad Request invalid service_id Service_id inválido. Validar el service_id (debe ser un número entero).
    400 - Bad Request invalid JSON body El JSON es inválido. Validar el esquema de query establecida.
    404 - Not Found can't update delivery custom No se puedo realizar la actualización de configuración debido a que no existe suscripción a Envíos Turbo para la combinación de user_id y service_id enviada. Validar el user_id y service_id en el endpoint.

    Gestión de Ítems Turbo

    La gestión de ítems en Turbo implica la activación de Turbo para dichos ítems. A fin de lograrlo, es crucial considerar lo siguiente:


    1. Antes de activar Turbo, es necesario habilitar Flex.
    2. Los ítems que cuentan con Flex activo se ofrecerán por Turbo siempre que cumplan con las restricciones de dimensiones y peso de Envíos Turbo.
    3. La activación es automática una vez que se han cumplido los requisitos previos.



    Importante:
    Antes de publicar o editar un ítem utilizando en Turbo, es importante tener en cuenta los siguientes aspectos:
    1. Verificar que el vendedor ya tenga activo el tipo de logística Flex.
    2. Verificar que el ítem tenga activo Flex.
    3. Verificar que el ítem cumpla con las dimensiones establecidas:
    • Alto: 70 cm
    • Ancho: 70 cm
    • Largo: 70 cm
    • Peso: 30000 gr = 30 kg
    4. Tener en cuenta que si un ítem cumple estos requisitos, la activación es automática, es decir, Turbo aparecerá de manera inmediata en la publicación.
    5. Si no se desea ofrecer el ítem con Turbo, se recomienda desactivarlo o eliminarlo de Flex.
    Estos pasos asegurarán una gestión adecuada de los ítems en Mercado Libre y ayudarán a ofrecer la mejor experiencia de compra para los usuarios.