Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentación
Mercado Envíos
Mercado Envíos es una red de servicios de Mercado Libre que proporciona soluciones logísticas para mejorar la experiencia de vendedores y compradores. Además de coordinar con diversos operadores de la industria, la red logística de Mercado Envíos incluye centros de almacenamiento y distribución propios, agencias, y una flota terrestre y aérea en constante crecimiento. Conoce más sobre envíos para vendedores y mira nuestro webinar para integrarte:
Modalidades de Envíos
Mercado Envíos se divide en las siguientes modalidades:
- Mercado Envíos 1 (ME1): es una modalidad de envío que permite a los vendedores vender a través de Mercado Libre, utilizando su propia logística o servicios de terceros.
- Mercado Envíos 2 (ME2): es la modalidad de envío de Mercado Libre, donde se gestiona toda la logística utilizando diversos medios como correos, agencias, entre otros. Esta modalidad se divide a su vez en los siguiente tipos de logística:
- Custom: es una modalidad de envío donde el vendedor carga una tabla con los precios de envío por cada región y se encarga de la logística.
- Not Specified: es una modalidad de envío donde el vendedor no especifica ningún precio de envío para sus publicaciones y debe ponerse en contacto con el comprador para coordinar el envío.
Preferencias de envío de un ítem
Para establecer las preferencias de envío de un ítem en Mercado Libre de manera adecuada, es crucial tener en cuenta los siguientes puntos:
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/186288053336-3bcb9316-a477-47a5-9eb3-e8046ef68371.png)
La gestión de ítems en Mercado Libre, ya sea mediante publicación, edición o migración, está estrechamente vinculada a las preferencias de envío activas tanto del usuario como del ítem en cuestión. Estas preferencias determinan qué modalidades de envío están disponibles y deben ser revisadas cuidadosamente.
Servicios de Envíos disponibles por país
Para establecer las preferencias de envío de un ítem en Mercado Libre de manera adecuada, es crucial tener en cuenta los siguientes puntos:
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping_methods
Respuesta:
{
{
"id": 73328,
"name": "Normal a domicilio",
"type": "standard",
"deliver_to": "address",
"status": "active",
"site_id": "MLA",
"free_options": [
"country"
],
"shipping_modes": [
"me2"
],
"company_id": 17500240,
"company_name": "OCA",
"min_time": 72,
"max_time": null,
"currency_id": "ARS"
},
...
}
Parámetros de respuesta:
- id: es un identificador único para el tipo de envío.
- name: nombre descriptivo del servicio de envío.
- type: define el tipo de servicio de envío.
- deliver_to: Especifica el destino del envío. "address" indica que el paquete será entregado en una dirección física.
- status: indica el estado actual del servicio de envío. "active" significa que el servicio está actualmente disponible y operativo.
- site_id: país al que se aplica este servicio de envío.
- free_options: lista de opciones en las que el servicio de envío puede ser gratuito. En este caso, "country" indica que el envío puede ser gratuito a nivel nacional.
- shipping_modes: indica los modos de envío compatibles.
- company_id: identificador único de la empresa de logística que provee el servicio de envío.
- company_name: nombre de la empresa de logística que maneja el envío.
- min_time: el tiempo mínimo estimado de entrega del envío en horas.
- max_time: el tiempo máximo estimado de entrega del envío en horas.
- currency_id: identificador de la moneda utilizada para cualquier tarifa aplicable al servicio de envío.
Códigos de Estado de respuesta:
Código | Mensaje | Descripción | Recomendación |
---|---|---|---|
200 - OK | - | Se obtuvo correctamente la configuración actual. | - |
401 - Unauthorized | invalid access token | Access token inválido. | Validar el access_token. |
404 - Not Found | invalid_site_id | No existe el site_id. | Validar el site_id. |
Preferencias de envío de un usuario
Este endpoint permite conocer las preferencias de envío activas para un usuario y con esto validar previamente que el vendedor puede publicar o editar un item para los tipos de envío según su cuenta.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_preferences
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/12345678/shipping_preferences
Respuesta:
{
"local_pick_up": false,
"modes": [
"custom",
"not_specified",
"me2",
"me1"
],
"trusted_user": false,
"bulky": false,
"custom_calculator": "Axado",
"picking_type": null,
"thermal_printer": null,
"option": "in",
"tags": [
"optional_me1_allowed",
"turbo",
"flex2_migration"
],
"me2_enablers": [],
"carrier_pickup": false,
"items_combination": "enabled",
"services": [
153,
154,
251,
422,
431,
742746,
742748
],
"logistics": [
{
"mode": "me1",
"types": [
{
"type": "default",
"carrier_pickup": [],
"services": [
251,
153,
154
],
"default": true,
"status": "active"
}
]
},
{
"mode": "me2",
"types": [
{
"type": "drop_off",
"carrier_pickup": [],
"services": [
422,
431
],
"default": true,
"status": "active"
},
{
"type": "self_service",
"carrier_pickup": [],
"services": [
742746,
742748
],
"default": false,
"status": "active"
}
]
},
{
"mode": "custom",
"types": [
{
"type": "custom",
"carrier_pickup": [],
"services": null,
"default": true,
"status": "active"
}
]
},
{
"mode": "not_specified",
"types": [
{
"type": "not_specified",
"carrier_pickup": [],
"services": null,
"default": true,
"status": "active"
}
]
}
],
"label": {
"print_danfe": false,
"print_browser": false,
"print_voucher": false,
"print_summary": true,
"thermal_printer": null,
"page_size": "a4",
"page_format": "pdf"
},
"content_declaration_disabled": false,
"conciliation": {
"type": null
},
"mandatory_invoice_data": false,
"site_id": "MLA",
"free_configurations": [
{
"condition": {
"value": null,
"type": "all"
},
"rule": {
"default": true,
"free_mode": "country",
"value": null
}
}
],
"mandatory_settings": {}
}
-
local_pick_up: indica si el comprador tiene la opción de retirar el paquete en el domicilio del vendedor. Los valores posibles son:
- true: permite el retiro.
- false: no permite el retiro.
-
modes: lista de modos de envío configurados para el usuario. Los valores posibles son:
- custom
- not_specified
- me2
- me1
-
trusted_user: indica si el usuario es considerado confiable para vender en dominios restringidos. Los valores posibles son:
- true
- false
-
custom_calculator: indica si el usuario cuenta con una tabla de contingencia en Mercado Libre. Los valores posibles son:
- Axado: tiene ME1 activo con tabla de contingencia.
- true: tiene ME1 activo sin tabla de contingencia.
- false: no tiene ME1 activo.
- CBT: usuario CBT.
- thermal_printer: indica si se utiliza una impresora térmica.
-
option: opción de configuración de envío del usuario. Los valores posibles son:
- in: usuario tiene Mercado Envíos 2 activo para todas sus publicaciones.
- out: usuario anteriormente tenía habilitada la opción de Mercado Envíos 2. Sin embargo, esta funcionalidad ya no está activa para su cuenta.
- trial: usuario tiene Mercado Envíos 2 activo para algunas publicaciones.
- null: usuario nunca tuvo Mercado Envíos 2 activo.
-
tags: lista de etiquetas adicionales relacionadas con la configuración de envío del usuario. Los valores posibles son:
- optional_me1_allowed: me2 es la opción mandatoria, y me1 es la preferencia de envío opcional.
- optional_me2_allowed: me1 es la opción predeterminada, y me2 es la preferencia de envío opcional.
- turbo: logística turbo activa para el usuario.
-
me2_enablers: indica los habilitadores configurados para el vendedor. Los valores posibles son:
- bulky_fulfilllment
- bulky_cross_docking
- bulky_drop_off
- pharma
- cbt_fulfillment
- entre otros.
- carrier_pickup: indica si tiene habilitado un carrier para colectas.
- items_combination: indica si permite combinación en carrito.
- services: lista de identificadores de servicios disponibles.
- logistics: configuraciones logísticas detalladas para diferentes modos de envío, cada una con tipos específicos y sus atributos.
- label: configuraciones para la impresión de etiquetas, incluyendo opciones de impresión y tamaño/formato de la página.
- site_id: identificador del país del usuario en Mercado Libre.
Códigos de Estado de respuesta:
Código | Mensaje | Descripción | Recomendación |
---|---|---|---|
200 - OK | - | Se obtuvo correctamente la configuración actual. | - |
401 - Unauthorized | authorization value not present | Falta informar el access token | Informe un access token válido |
401 - Unauthorized | invalid access token | El access token informa es inválido o expirado | Informe un access token válido |
Consideraciones:
- La configuración predeterminada de un usuario con ME2 y ME1 activos es con optional_me1_allowed. Esto significa que ME1 está habilitado como un modo de envío opcional, y ME2 mandatorio.
- Si se desea realizar cualquier modificación en esta configuración, es necesario que el vendedor se comunique con su asesor comercial, justificando el cambio requerido.
- Es fundamental validar los modos de envío activos para cada usuario, ya que esto impacta directamente en cómo se gestionarán las publicaciones de sus productos. Los atributos clave a considerar son optional_me1_allowed y optional_me2_allowed.
- Recordar que todos los vendedores tienen habilitado custom y not_specified por defecto.
Consultar modos de envíos de una categoría
Este endpoint permite consultar las preferencias de envío disponibles para la categoría y sirve para identificar previamente las opciones de envío.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/$CATEGORY_ID/shipping_preferences
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLA418448/shipping_preferences
Respuesta:
{
"dimensions": {
"height": 5,
"width": 18,
"length": 25,
"weight": 650
},
"logistics": [
{
"types": [
"default"
],
"mode": "me1"
},
{
"types": [
"drop_off",
"xd_drop_off",
"self_service",
"cross_docking",
"fulfillment"
],
"mode": "me2"
},
{
"types": [
"not_specified"
],
"mode": "not_specified"
},
{
"types": [
"custom"
],
"mode": "custom"
}
],
"me2_restrictions": null,
"restricted": false,
"source": {
"origin": "categories",
"identifier": "MLA418448"
},
"date_created": null,
"last_modified": null,
"category_id": "MLA418448"
}
Parámetros de respuesta:
- dimensions: son las dimensiones base (default) de los productos de esta categoría.
- logistics: muestra los tipos logísticos (mode y type) habilitados para la categoría.
-
me2_restrictions: en caso que haya alguna restricción que no permita me2, estará identificado. Posibles valores:
- fbm_non_totable
- flex_ne
- cbt_fulfillment
- bulky_drop_off
- farma
- fragile
- bulky_cross_docking
- bulky_fulfillment
- restricted: en caso que haya restricción de me2, estará identificado con true, de lo contrario, es false.
Códigos de estado de respuesta:
Código | Mensaje | Descripción | Recomendación |
---|---|---|---|
200 - OK | - | Se obtuvo correctamente la configuración actual. | - |
404 - Not Found | Category not found | No existe la categoría. | Validar el category_id. |
Consultar atributos de shipping por dominio
Este endpoint permite consultar los atributos de preferencias de envío por dominio, para identificar los atributos requeridos para las reglas de envíos a ME2.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/shipping_attributes
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_domains/MLA-AUTOMOTIVE_TIRES/shipping_attributes
Respuesta:
{
"domain_id": "MLA-AUTOMOTIVE_TIRES",
"attributes": [
{
"id": "RIM_DIAMETER",
"type": "NUMBER_UNIT",
"unit": "\"",
"index": 1,
"ranges": null
},
{
"id": "TIRES_NUMBER",
"type": "INTEGER",
"unit": "",
"index": 2,
"ranges": null
},
{
"id": "SECTION_WIDTH",
"type": "NUMBER_UNIT",
"unit": "mm",
"index": 3,
"ranges": null
}
],
"client_id": app_id,
"date_created": "2018-11-09T15:31:02.040-03:00",
"last_modified": "2023-09-11T15:59:30.175-03:00"
}
Parámetros de respuesta:
- domain_id: ID del dominio consultado.
- attributes: atributos que determinan la preferencia de envío de un item.
Códigos de estado de respuesta:
Código | Mensaje | Descripción | Recomendación |
---|---|---|---|
200 - OK | - | Se obtuvo correctamente la configuración actual. | - |
404 - Not Found | Domain does not exist | No existe el dominio. | Validar el domain_id. |
Consultar modos de envíos de un ítem para el usuário
Como paso extra, es posible realizar una validación antes de ejecutar el POST del Item para identificar probar si la API permite el modo de envío que estás intentando actualizar. Para ellos, debe enviar las informaciones abajo, enfocando en los atributos de la publicación. Recuerde de observar el recurso de catalog_domaing/$ID/shipping_attributes para probar con los atributos que se apuntan como necesarios para actualización a ME2.
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 'x-multichannel: true' 'X-Format-New: true' -H "Content-Type: application/json" -d https://api.mercadolibre.com/users/$USER_ID/shipping_modes
Ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 'x-multichannel: true' 'X-Format-New: true' -H "Content-Type: application/json" -d https://api.mercadolibre.com/users/1818431734/shipping_modes
{
"buying_mode": "buy_it_now",
"category_id": "MLA418448",
"channels": [
{
"id": "marketplace"
}
],
"condition": "new",
"dimensions": null,
"is_internal": true,
"is_new_listing": false,
"item_currency": "ARS",
"item_id": null,
"item_price": 5788,
"listing_type_id": "gold_pro",
"new_format": true,
"sale_terms": [],
"seller_id": 419059118,
"site_id": "MLA",
"source": "",
"title": "Título de teste",
"local_pick_up": false,
"to_catalog_internal": false,
"to_modes_internal": false,
"traced": false,
"verbose": false
}
Respuesta:
{
"buying_mode": "buy_it_now",
"category_id": "MLA418448",
"channels": [
{
"id": "marketplace"
}
],
"condition": "new",
"dimensions": null,
"is_internal": true,
"is_new_listing": false,
"item_currency": "ARS",
"item_id": null,
"item_price": 5788,
"listing_type_id": "gold_pro",
"new_format": true,
"sale_terms": [],
"seller_id": 419059118,
"site_id": "MLA",
"source": "",
"title": "Título de teste",
"local_pick_up": false,
"to_catalog_internal": false,
"to_modes_internal": false,
"traced": false,
"verbose": false
}
Parámetros de respuesta:
- mode: modos de envíos permitidos.
- logistic_types.type: tipos de logísticas acorde a cada modo de envío.
- logistic_types.default: si el tipo de logística es definido por patrón.
- logistic_types.attributes: atributos del tipo de la logística.
- logistic_types.attributes.dimensions: en caso que haya una dimensión default, se completa.
- logistic_types.attributes.costs: reglas relacionadas al costo de envío.
- logistic_types.attributes.adoption: -
- logistic_types.attributes.free_shipping: si es default la configuración de envío grátis.
- logistic_types.attributes.local_pick_up: -
- logistic_types.attributes.tags: tags internas relacionadas a las características de cada tipo de logística.
Consultar un ítem
También es posible validar ciertas informaciones relacionadas al envío de la publicación consultando su detalle por la API /Items.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1718222111
Respuesta
{
"id": "MLA1718222111",
"site_id": "MLA",
"title": "Silla Director Coleman Sillon Plegable Acero Resistente 136k Color Rojo",
"seller_id": 309720111,
"category_id": "MLA79227",
"user_product_id": "MLAU255412797",
"official_store_id": 66111,
"price": 105622,
"base_price": 105622,
"original_price": 126900,
"currency_id": "ARS",
"initial_quantity": 4,
"available_quantity": 2,
"sold_quantity": 2,
...
"shipping": {
"mode": "me2",
"methods": [],
"tags": [
"self_service_out",
"mandatory_free_shipping"
],
"dimensions": null,
"local_pick_up": true,
"free_shipping": true,
"logistic_type": "cross_docking",
"store_pick_up": false
},
...
}
Parámetros de respuesta:
- shipping.mode: Indica el tipo de envío utilizado.
-
shipping.tags: Etiquetas de envío del ítem. Valores posibles:
- self_service_in (se ofrece flex como tipo de envío).
- self_service_out (no se ofrece flex como tipo de envío).
- mandatory_free_shipping (el ítem superó el límite de precio establecido por Mercado Libre). Para mayor detalle, revisar Costos de envío y SLA.
- shipping.dimensions: Dimensiones del producto, en el formato: altura x ancho x largo, peso. Esto debe ser informado solo para migraciones a ME1.
- shipping.local_pick_up: Indicador booleano que muestra si está disponible la opción de retiro en persona.
- shipping.free_shipping: Este es un indicador booleano que determina si el envío es gratuito. En caso de que el tag esté configurado como “mandatory_free_shipping”, el envío se considerará siempre gratuito, independientemente del valor que se envíe.
- shipping.logistic_type: Tipo de logística del envío.
- shipping.store_pick_up: Indicador booleano que muestra si está disponible la opción de recogida en tienda.
Ahora que ya sabes cómo validar previamente las informaciones de su vendedor, revise las siguientes documentaciones para saber cómo gestionar las publicaciones: