Documentación Mercado Libre

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

Documentación

Última actualización 15/05/2024

Precios por variación

Importante:
La iniciativa estará en producción a partir de julio de 2024, comenzando por México y encendiendo progresivamente en Brasil y Argentina. 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, será necesario simular el flujo utilizando mocks creados desde las integraciones.

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:
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.

Puede iniciar pruebas publicando items sin variantes, pero es fundamental conocer que el campo family_name aún no se encuentra disponible. Para que no falle la ejecución deberán omitir dicho campo y adicionar el título de la publicación.

A continuación presentamos algunas consideraciones que debe 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 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",
   "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"
   ]
}

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 de la misma familia, 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.


Consideraciones:

¿Qué sucede si el vendedor modifica el campo family_name?
Si se modifica el family_name asociado a un ítem, este se replicará al User Product y esto disparará dos 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?
En un primer momento el campo será ignorado y retornaremos un warning en la respuesta a la llamada PUT 'https://api.mercadolibre.com/items' para notificar de dicha acción. El end game es disparar 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?
Si se modifica la información en el ítem de tal manera que el cálculo automático de user_product_id lo relacione a otro User Product.


¿Cómo convivirá UP y catálogo?
  • Item no tiene variaciones y es (catalog_listing = true): El flujo de catalogo 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"
}


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": [
      …
   ]
}


Siguiente: Stock Distribuido.