Developers

Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.

Última actualización 19/07/2024

Precio por variación

Importante:

La iniciativa estará en producción a partir de agosto de 2024, comenzando por Argentina y encendiendo progresivamente en Brasil, México y resto de sites en septiembre 2024.

Te proporcionamos esta información para que puedas analizarla y ajustar el backlog de desarrollo. Para realizar pruebas, será necesario simular el flujo utilizando mocks creados desde las integraciones o podrás realizar pruebas bajo el nuevo modelo de UP, solicitándolo en el siguiente formulario para que puedas solicitar la ambientación de tus usuarios de TEST. Las activaciones serán realizadas hasta 15 días.

La iniciativa de precio por variación tiene como objetivo proporcionar al vendedor la capacidad de ofrecer diferentes condiciones de venta para las variantes de un mismo producto, lo que le permite aplicar sus estrategias de venta de manera más flexible y escalable.

Publicar un ítem

Importante:

Te recomendamos comenzar a analizar el impacto y planear el backlog, que tendrá la integración al momento de publicar items sin el array de variations ni el campo title. Puedes iniciar pruebas publicando items sin variantes, pero es fundamental conocer que el campo family_name aún no se encuentra disponible para todos los usuarios. Para que no falle la ejecución deberán omitir dicho campo y adicionar el título de la publicación.

Tendremos 2 tipos de usuarios los que podrán publicar con el modelo anterior y los que podrán a comenzar a publicar con el nuevo modelo de User Products (convivirán ambos modelos). Dichos sellers podrás identificarlo a través del tag "user_product_seller" en el API de users.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/{User_id}

Respuesta:


{
    "id": 206946886,
    "nickname": "TETE6838590",
    "registration_date": "2016-02-24T15:18:42.000-04:00",
    "first_name": "Pedro",
    "last_name": "Picapiedras",
    "tags": [
        "normal",
        "test_user",
        "user_info_verified",
        "user_product_seller"
    ]
}

Consideraciones

A continuación te presentamos algunas consideraciones que debes tener en cuenta al momento de querer publicar un ítem bajo el nuevo modelo de UP.

El nuevo campo family_name es un campo requerido que el vendedor deberá completar, dicho campo será una descripción genérica del ítem, que abarque a los distintos User Products de una misma familia, se recomienda usar texto genérico y representativo de los ítems, por ejemplo:

Family name: "Apple iPhone 256GB"
Item_1: "Apple iPhone 256GB Rojo"
Item_2: "Apple iPhone 256GB Azul"

Nota:

El campo family_name será utilizado para el cálculo del family_id, para más detalle pueden consultar el detalle de Familia en Conceptos importantes.
El precio y las condiciones de venta pueden cambiar en cada ítem que se publica, te recomendamos consultar la sección Precios de productos.

Adicionalmente, el campo title no debe ser enviado por el vendedor ya que Mercado Libre lo completará automáticamente, con la información del ítem específico o del producto. Lo anterior se realiza con el objetivo de tener items más estandarizados, tomando como base el dominio, los atributos, el family_name, entre otros.

A modo de ejemplo, estaremos publicando dos ítems de una misma familia, comparten: family_name, dominio, condición, seller_id y GTIN.

Primer ítem, en color azul:

curl -X POST https://api.mercadolibre.com/items -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
   "family_name": "Apple iPhone 256GB",
   "category_id": "MLM1055",
   "price": 17616,
   "currency_id": "MXN",
   "available_quantity": 6,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "3 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía del vendedor"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Azul"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Sí"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Desbloqueado"
       }
   ]
}'

Segundo item, en color rojo:

curl -X POST https://api.mercadolibre.com/items -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
   "family_name": "Apple iPhone 256GB",
   "category_id": "MLM1055",
   "price": 19800,
   "currency_id": "MXN",
   "available_quantity": 8,
   "sale_terms": [
       {
           "id": "WARRANTY_TIME",
           "value_name": "3 meses"
       },
       {
           "id": "WARRANTY_TYPE",
           "value_name": "Garantía del vendedor"
       }
   ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "condition": "new",
   "pictures": [ … ],
   "attributes": [
       {
           "id": "BRAND",
           "value_name": "Apple"
       },
       {
           "id": "COLOR",
           "value_name": "Rojo"
       },
       {
           "id": "GTIN",
           "value_name": "195949034862"
       },
       {
           "id": "RAM",
           "value_name": "6 GB"
       },
       {
           "id": "IS_DUAL_SIM",
           "value_name": "Sí"
       },
       {
           "id": "MODEL",
           "value_name": "iPhone 15"
       },
       {
           "id": "CARRIER",
           "value_name": "Desbloqueado"
       }
   ]
}'

Ejemplo de respuesta para la creación de un ítem:

{
   "id": "MLM2061397137",
   "site_id": "MLM",
   "title": "Apple iPhone 256GB Rojo",
   "family_name": "Apple iPhone 256GB",
   "seller_id": 1008002397,
   "category_id": "MLM1055",
   "user_product_id": "MLMU367467963",
   "official_store_id": null,
   "price": 19800,
   "base_price": 19800,
   "original_price": null,
   "inventory_id": null,
   "currency_id": "MXN",
   "initial_quantity": 8,
   "available_quantity": 8,
   "sold_quantity": 0,
   "sale_terms": [ …  ],
   "buying_mode": "buy_it_now",
   "listing_type_id": "gold_special",
   "start_time": "2024-05-07T12:57:08.016Z",
   "stop_time": "2044-05-02T04:00:00.000Z",
   "end_time": "2044-05-02T04:00:00.000Z",
   "expiration_time": "2024-07-26T12:57:08.119Z",
   "condition": "new",
   "permalink": "http://articulo.mercadolibre.com.mx/MLM-2061397137-apple-iphone-15-256-gb-rojo-_JM", /*el permalink va a redirigir al UPP del item*/
   "pictures": [ … ],
   "video_id": null,
   "descriptions": [],
   "accepts_mercadopago": true,
   "non_mercado_pago_payment_methods": [],
   "shipping": { … },
   "international_delivery_mode": "none",
   "seller_address": { … },
   "seller_contact": null,
   "location": {},
   "geolocation": { …  },
   "coverage_areas": [],
   "attributes": [
      … 
   ],
   "warnings": [ … ],
   "listing_source": "",
   "variations": [],
   "thumbnail_id": "759471-MLA71782897602_092023",
   "thumbnail": "http://mlm-s1-p.mlstatic.com/759471-MLA71782897602_092023-I.jpg",
   "status": "active",
   "sub_status": [],
   "tags": [ … ],
   "warranty": "Garantía del vendedor: 3 meses",
   "catalog_product_id": null,
   "domain_id": "MLM-CELLPHONES",
   "seller_custom_field": null,
   "parent_item_id": null,
   "differential_pricing": null,
   "deal_ids": [
      "MLM23369",
      "MLM52903"
   ],
   "automatic_relist": false,
   "date_created": "2024-05-07T12:57:08.177Z",
   "last_updated": "2024-05-07T12:57:08.177Z",
   "health": null,
   "catalog_listing": false,
   "item_relations": [],
   "channels": [
       "marketplace",
       "mshops"
   ]
}

Modificación de items

Para realizar cambios en los ítems existentes, deberás continuar ejecutando un PUT al recurso /items. Mercado Libre replicará esta modificación de manera asíncrona en todos los ítems del mismo User Product, siempre y cuando se modifiquen atributos compartidos, como la guía de talles. Es importante recordar que en el nuevo modelo no se permitirá la creación de variaciones mediante un llamada POST o PUT en el recurso de ítems.

Modificar familia

Podrás modificar el family_name a través del siguiente recurso, teniendo en cuenta que sólo podrá ser modificado si los ítems asociados user-product del ítem que se están queriendo modificar aún no tienen ventas.

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "family_name": "Nuevo family name"
}
https://api.mercadolibre.com/items/$ITEM_ID/family_name

Respuesta:

{
   "family_name": "Nuevo family name"
}

Posibles status:

Se agrega un nuevo código de error para la validación del largo del family_name.

Id: 462, “Family Name length is over of 120 characters”

Consideraciones:

¿Qué sucede si el vendedor modifica el campo family_name?
Si se modifica el family_name asociado a un ítem, se recalcula el campo título del ítem y adicionalmente la modificación se replicará al User Product, lo que disparará dos posibles acciones:

El recálculo del family_id que hará que dicho User Product se traslade a otra familia de ser necesario.
Se replicará el nuevo family_name en todas las condiciones de venta (ítems) asociadas al User Product.

¿Qué sucede si alguien intenta modificar el campo title del ítem?
Se dispara un error de tipo bad request.

¿Un ítem puede cambiar de familia?
Modificar los atributos de los ítems pueden hacer que salgan de la familia, por ejemplo, al cambiar marca, modelo, etc.

¿El user_product_id del item puede cambiar?
No es un campo editable. En caso de que cambien los atributos del item, tal y como el family_name, el user_product_id continúa siendo el mismo. Solo actualizarán los atributos editados de todas las condiciones de venta conectadas a este mismu User Products.

¿Cómo convivirá UP y catálogo?

Item no tiene variaciones y es (catalog_listing = true): El flujo de catálogo no se ve impactado, por lo que se crea la PDP con el catalog_product_id, para más detalle consulta publicaciones en catalogo.
Item no tiene variaciones y es (catalog_listing = false): Se crea la UPP (User Products Page) con el item_id y user_product_id.

Consultar un User Product

Podrás obtener el detalle de un User Prodcut por medio del siguiente llamado:

curl -X GET https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Ejemplo consultando un UP específico:

curl -X GET https://api.mercadolibre.com/user-products/MLBU22012 -H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
   "id": "MLBU22012",
   "name": "iPhone 14 Pro Max",
   "user_id": 1295303699,
   "domain_id": "MLB-CELLPHONES",
   "attributes": [
       {
           "id": "BRAND",
           "name": "Marca",
           "values": [
               {
                   "id": "123",
                   "name": "Apple",
                   "struct": null
               }
           ]
       },
       {
           "id": "MODEL",
           "name": "Modelo",
           "values": [
               {
                   "id": "123",
                   "name": "iPhone 14 Pro Max",
                   "struct": null
               }
           ]
       },
       {
           "id": "INTERNAL_MEMORY",
           "name": "Internal Memory",
           "values": [
               {
                   "id": "123",
                   "name": "10 GB",
                   "struct": {
                       "number": 10.0,
                       "unit": "GB"
                   }
               }
           ]
       },
       {
           "id": "ITEM_CONDITION",
           "name": "Condición del ítem",
           "values": [
               {
                   "id": "2230284",
                   "name": "Nuevo",
                   "struct": null
               }
           ]
       }
   ],
   "pictures": [
       {
           "id": "856054-MLB49741387485_042022",
           "secure_url": "https://http2.mlstatic.com/D_856054-MLA49741387485_042022-O.jpg"
       },
       {
           "id": "793512-MLB51622915557_092022",
           "secure_url": "https://http2.mlstatic.com/D_793512-MLA51622915557_092022-O.jpg"
       }
   ],
   "thumbnail": {
       "id": "856054-MLA49741387485_042022",
       "secure_url": "https://http2.mlstatic.com/D_856054-MLA49741387485_042022-O.jpg"
   },
   "catalog_product_id": "MLB19615318",
   "family_id": 18446744000000000615, /*Familia del UP*/
   "tags": [
       "test"
   ],
   "date_created": "2023-02-13T02:46:20.528+0000",
   "last_updated": "2023-02-13T02:46:20.528+0000"
}

Notificaciones de familias

Notificaremos al vendedor cuando una familia sea alterada, esto se debe a que un User Product experimenta un cambio en alguno de los atributos comprometidos en el cálculo de la familia, lo que provoca que el producto migre a otra familia.

El mensaje de notificación contendrá la clave family_id con el ID de la familia afectada.

En caso de que la familia haya sido modificada, se enviará el mensaje con el ID de la nueva familia de destino. Si se crea una nueva familia (como resultado de la creación de un User Product), se incluirá el ID de la nueva familia en la notificación. Por último, si se elimina la familia original debido a que el User Product ha migrado a otra familia, se enviará el ID de la familia anterior en la notificación.

Ejemplo:


{
"_id": "2e4f6253-ebcc-421d-9d0b-97f80290ac5d",
"topic": "user-products-families",
"resource": "/sites/$SITE_ID/user-products-families/$FAMILY_ID",
"user_id": 123456789,
"application_id": 213123389095511,
"sent": "2024-07-11T18:43:50.793Z",
"attempts": 1,
"received": "2024-07-11T18:43:50.699Z"
}

Consultar los User Products de una familia

Podrás obtener los User Products asociados a una familia en particular, por medio del siguiente llamado.

curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/user-products-families/$FAMILY_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Ejemplo del recurso para una familia y un site en específico:

curl -X GET https://api.mercadolibre.com/sites/MLA/user-products-families/9871232123 -H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
   "user_products_ids": [
       "MLAU1234",
       "MLAU1235",
       "MLAU1236"
   ],
   "family_id": 9871232123,
   "site_id": "MLA",
   "user_id": 1234
}

Busqueda de items por User Product

Podrás hacer el search de ítems utilizando un filtro el campo user_product_id.

curl -X GET https://api.mercadolibre.com/users/$SELLER_ID/items/search?user_product_id=$USER_PRODUCT_ID -H 'Authorization: Bearer $ACCESS_TOKEN'

Ejemplo para un UP específico:

curl -X GET https://api.mercadolibre.com/users/1234/items/search?user_product_id=MLBU206642488 -H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
   "seller_id": "1234",
   "results": [
       "MLB664681522",
       "MLB664648534",
       "MLB664648532",
       "MLB664635674"
   ],
   "paging": {
       "limit": 50,
       "offset": 0,
       "total": 4
   },
   "query": null,
   "orders": [
       … 
   ],
   "available_orders": [
      …
   ]
}

Elegibilidad de los ítems - UPTIN

Importante:

La iniciativa estará en producción a partir de agosto de 2024, comenzando por Argentina y encendiendo progresivamente en Brasil, México y resto de sites en septiembre 2024. Por el momento no contaremos con un entorno de pruebas disponible.

Te proporcionamos esta información para que puedas analizarla y ajustar el backlog de desarrollo. Para realizar pruebas de UPTIN, será necesario simular el flujo utilizando mocks creados desde las integraciones. Todavia no tenemos ambiente de pruebas para esto.

Los vendedores van a poder migrar sus ítems al nuevo modelo de precio por variación, por lo que introducimos el concepto de UPtin para referirnos al proceso de migrar un ítem que se encuentra en el modelo anterior hacia el nuevo modelo de publicación de user products.

Consideraciones de elegibilidad:

Un ítem sólo será elegible para UPtin si:

El atributo "user_product_id" del ítem orginal es diferente de nulo.
No existen User Products duplicados por variación.
El ítem original tiene variaciones.

Para consultar la elegibilidad de los ítems antiguos para el nuevo formato de User Products, deberás utilizar el siguiente recurso.

Llamada:

curl -X GET https://api.mercadolibre.com/sites/$SITE_ID/items/$ITEM_ORIGINAL/user_product_listing -H 'Authorization: Bearer $ACCESS_TOKEN'

Ejemplo:

curl -X GET https://api.mercadolibre.com/sites/MLA/items/MLA12345678/user_product_listing -H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
  "is_valid": true,
  "cause": {
    "code": 12,
    "message": ""
  }
}

Los atributos indican:

is_valid: true, indica que el ítem es candidato a realizar UPtin. Y false para casos donde no sin candidatos.

Migración ítems

La migración consistirá en crear un nuevo ítem por cada variación que contiene el ítem original, este proceso se realizará de manera asíncrona, por lo que mientras concluye la migración, el item original permanecerá activo y el seller seguirá vendiendo con dicho ítem hasta tanto se creen y activen todos los ítems de las variaciones originales.

Una vez concluída la migración, el ítem original será cerrado (status = “closed”), todo ítem creado a partir de un UPtin contará con el tag variations_migration, y enviaremos una notificación en el tópico de ítems en cada caso (items nuevos y item cerrado).

Para ejecutar el UPtin deberás utilizar el siguiente recurso, indican el ítem a migrar en el body request (deberás realizar una petición por cada ítem a migrar).

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLM/items/user_product_listings
{
"item_id": "MLM1234"
}

Respuesta:

Status migración

Para que puedas conocer el status de migración de cada ítem, sus variantes y los nuevos ítems creados, será posible realizarlo a través del siguiente recurso.

Llamada:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ORIGINAL/migration_live_listing? -H 'Authorization: Bearer $ACCESS_TOKEN'

Ejemplo:

curl -X GET https://api.mercadolibre.com/items/MLA123456/migration_live_listing? -H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
   "old_item_id": "MLA123456",
   "migration_completed": "", 
   "new_items": [
       {
           "new_item_id": "MLA789012",
           "variation_id": 45674567
       {
           "new_item_id": "MLA789022",
           "variation_id": 987654
       }
   ],
   "date_created": "..",
   "last_updated": "..."
}

Status de respuesta:

Status 200 y atributo date_created es null, quiere decir que la migración sigue en proceso.
Status 200 y atributo date_created es diferente de null, quiere decir que la migración concluyó exitosamente y se muestra el timestamp de finalización.
Status 404 - no fue posible realizar la migración.

Activación de pruebas

Podrás hacer una solicitud de activación en tu cuenta de pruebas a través de este formulario.

Siguiente: Stock Distribuido.