Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Última actualización 22/12/2023
Envíos Flex
Áreas de cobertura por países
Para poder ofrecer envíos flex, 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) - Córdoba |
| Brasil |
- São Paulo - Río de Janeiro - Brasilia - Belo Horizonte - Porto Alegre - Salvador Bahía - Curitiba |
| México |
- CDMX (Zona Metropolitana del Valle de México) - Mérida |
| Chile |
- Santiago (Región Metropolitana) - Valparaíso |
| Colombia |
- Bogotá - Medellín - Cali |
| Uruguay |
- Montevideo - Canelones |
| Perú | - Lima (Área Metropolitana) |
| Ecuador | - Quito |
Configurar un usuario de test
Para configurar la funcionalidad de Envíos Flex para usuarios de prueba, tomar en cuenta:
1. Inicie sesión en la cuenta en la que desea habilitar Envío Flex.
2. Asegúrese de que la cuenta tenga publicaciones activas en ME2.
3. Verifique que su cuenta tenga una reputación Amarilla o Verde.
4. Asegúrese de tener una dirección de correo compatible con el área de cobertura de su país.
5. Configure la dirección de envío de acuerdo con las áreas de cobertura en los países correspondientes.
6. Active Envíos Flex a la cuenta.
Una vez que haya completado estos pasos, debería poder utilizar Envíos Flex como usuario de prueba.
Consultar suscripciones de un usuario
Este endpoint permite consultar las suscripciones que tiene un usuario.
- Si el usuario solo activó Flex, tendrá una única suscripción.
- Si el usuario también activó Turbo, tendrá 2 suscripciones, dado que para activar a Turbo, el usuario debe estar debe tener activo Flex primero.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/subscriptions/v1Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/subscriptions/v1Respuesta:
[
{
"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 ("FLEX" en este caso).
configuration_type: Tipo de configuración de la suscripción ("FLEX" 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 Flex |
| 400 - Bad Request | can't access to resource | Site_id inválido | Validar si el site_id está habilitado para Envíos Flex |
| 404 - Not Found | user not found | No existe el usuario | Validar el user_id |
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 Flex.
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/configuration/v3Ejemplo:
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: 736230) { 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 zones { enabled id is_mandatory label neighborhoods price { cents currency_id decimal_separator fraction symbol } selected } availables { cutoff capacity_range { from to } ranges } 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": 50
},
"cutoff": [
12,
13,
14,
15,
16,
17,
18
],
"ranges": [
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21
]
},
"delivery_ranges": {
"saturday": null,
"sunday": null,
"week": [
{
"calculated_cutoff": 14,
"capacity": 30,
"et_hour": 14,
"from": 12,
"processing_time": 0,
"to": 21,
"type": "cpt"
}
]
},
"delivery_window": "same_day",
"disabled_features": [
"CUTOFF_BY_ZONE",
"CAPACITY_BY_DAY"
],
"is_moderated": false,
"subscription": {
"creation_date": "2023-08-02T06:34:40Z",
"service_id": 736230,
"site_id": "MLA",
"status": {
"id": "in"
},
"training_times": null,
"user_id": 1438865529
},
"working_days": [
"week"
],
"zones": [
{
"enabled": true,
"id": "Almirante_Brown",
"is_mandatory": false,
"label": "Almirante Brown",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Avellaneda",
"is_mandatory": false,
"label": "Avellaneda",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Berazategui",
"is_mandatory": false,
"label": "Berazategui",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "CABA",
"is_mandatory": false,
"label": "CABA",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1114",
"symbol": "$"
},
"selected": true
},
{
"enabled": true,
"id": "Esteban_Echeverria",
"is_mandatory": false,
"label": "Esteban Echeverría",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Ezeiza",
"is_mandatory": false,
"label": "Ezeiza",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Florencio_Varela",
"is_mandatory": false,
"label": "Florencio Varela",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Hurlingham",
"is_mandatory": false,
"label": "Hurlingham",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Ituzaingo",
"is_mandatory": false,
"label": "Ituzaingó",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Jose_C_Paz",
"is_mandatory": false,
"label": "José C Paz",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Lanus",
"is_mandatory": false,
"label": "Lanús",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Lomas_de_Zamora",
"is_mandatory": false,
"label": "Lomas de Zamora",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Malvinas_Argentinas",
"is_mandatory": false,
"label": "Malvinas Argentinas",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "La_Matanza_1",
"is_mandatory": false,
"label": "La Matanza Norte",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "La_Matanza_2",
"is_mandatory": false,
"label": "La Matanza Sur",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Merlo",
"is_mandatory": false,
"label": "Merlo",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Moreno",
"is_mandatory": false,
"label": "Moreno",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Moron",
"is_mandatory": false,
"label": "Morón",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Quilmes",
"is_mandatory": false,
"label": "Quilmes",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Fernando",
"is_mandatory": false,
"label": "San Fernando",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Isidro",
"is_mandatory": false,
"label": "San Isidro",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Martin",
"is_mandatory": false,
"label": "San Martín",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Miguel",
"is_mandatory": false,
"label": "San Miguel",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Tigre",
"is_mandatory": false,
"label": "Tigre",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Tres_De_Febrero",
"is_mandatory": false,
"label": "Tres de Febrero",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Vicente_Lopez",
"is_mandatory": false,
"label": "Vicente López",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
}
]
}
}
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.cutoff: Detalle de los cortes disponibles.
- availables.ranges: Detalle de los rangos disponibles.
- delivery_ranges.saturday: Rangos de entrega y capacidad para los sábados.
- delivery_ranges.sunday: Rangos de entrega y capacidad para los domingos.
- delivery_ranges.week: Rangos de entrega y capacidad para los días de la semana.
disabled_features: Características deshabilitadas para el servicio, incluyendo 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.
zones: Información sobre las zonas disponibles para el servicio.
- zones.selected: Indica si la zona está seleccionada (true/false).
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 Flex |
| 400 - Bad Request | can't access to resource | Site_id inválido | Validar si el site_id está habilitado para Envíos Flex |
| 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 Flex 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 Plazo de Entrega y Límite de Envíos
A través de este endpoint, es posible configurar diferentes aspectos para Envíos Flex como:
- Ventana de Entrega
- Rangos de Horario de Entrega
- Horario de Corte
- 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/custom/v3Ejemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/delivery/custom/v3
{
"delivery_window": "same_day",
"delivery_ranges": {
"week": [
{
"from": 12,
"to": 21,
"capacity": 44,
"cutoff": 16
}
],
"saturday": [
{
"from": 12,
"to": 21,
"capacity": 33,
"cutoff": 14
}
],
"sunday": [
{
"from": 12,
"to": 21,
"capacity": 33,
"cutoff": 14
}
]
}
}
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 Flex 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 Flex
Este endpoint permite agregar más áreas de coberturas para Envíos Flex.
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/zone/v3Ejemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/coverage/zone/v3
{
"zones": [
{
"id": "Almirante_Brown"
},
{
"id": "Avellaneda"
},
{
"id": "CABA"
}
]
}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 Flex para la combinación de user_id y service_id enviada. | Validar el user_id y service_id en el endpoint. |
Consultar Flex en el ítem
Este endpoint te permite consultar si el ítem está habilitado para Envíos Flex o no.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403Respuesta:
Status: 204 No ContentCódigos de Estado de respuesta:
| Código | Mensaje | Descripción | Recomendación |
|---|---|---|---|
| 204 - No Content | - | Ítem habilitado para Envíos Flex. | - |
| 403 - Forbidden | item down | Ítem no ofrece Envíos Flex. | Validar las modalidades de envío del ítem. |
| 404 - Not Found | item not found | El país está deshabilitado para Envíos Flex. | Validar los países con Envíos Flex. |
Activar Flex en el ítem
Este endpoint permite activar la opción de Envíos Flex al ítem.
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_IDEjemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403Respuesta:
Status: 204 No Content| Código | Mensaje | Descripción | Recomendación |
|---|---|---|---|
| 204 - No Content | - | Ítem actualizado correctamente para ofrecer Envíos Flex. | - |
| 400 - Bad Request | item is already in flex | Ítem ya se encuentra con Envíos Flex. | - |
| 403 - Forbidden | item down | Ítem no ofrece Envíos Flex. | Validar las modalidades de envío del ítem. |
| 404 - Not Found | item not found | Ítem no encontrado. | Validar los países con Envíos Flex. |
Consultar estado del Ítem
Antes de activar flex a un ítem, es necesario realizar una validación para asegurarse de que el ítem se encuentre en el estado 'active'. Esto se puede verificar mediante el endpoint para obtener un item y luego consultar el atributo 'status'.
Llamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/items?ids=$ITEM_ID&attributes=statusEjemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/items?ids=MLA1136716168&attributes=statusRespuesta:
[
...
"status": "active",
...
]Desactivar Flex en el ítem
Este endpoint permite desactivar la opción de Flex en el ítem.
Llamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_IDEjemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403Respuesta:
Status: 204 No ContentCódigos de Estado de respuesta:
| Código | Mensaje | Descripción | Recomendación |
|---|---|---|---|
| 204 - No Content | - | Ítem actualizado correctamente para dejar de ofrecer Envíos Flex. | - |
| 400 - Bad Request | item is already in flex | Ítem ya se encuentra con Envíos Flex. | - |
| 403 - Forbidden | item down | Ítem no ofrece Envíos Flex. | Validar las modalidades de envío del ítem. |
| 404 - Not Found | item not found | Ítem no encontrado. | Validar los países con Envíos Flex. |
Identificar el código del transportista
Este endpoint facilita la identificación del transportista asignado a un envío, lo que resulta útil para registrar cambios de transportista durante el proceso de entrega.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/flex/sites/$SITE_ID/shipments/$SHIPMENT_ID/assignment/v1Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/flex/sites/MLA/shipments/40070866801/assignment/v1Respuesta:
{
"driver_id": 1234
}Códigos de Estado de respuesta:
| Código | Mensaje | Descripción | Recomendación |
|---|---|---|---|
| 200 - OK | - | Transportista asignado. | - |
| 404 - Not Found | shipment_id not found | No posee transportista asignado o no se encuentra la ruta abierta (envío pendiente de ser entregado). No existe (shipment inexistente). |
Validar el estado del envío o shipment_id. |