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 26/03/2024

Precio por variación

Importante:
Esta iniciativa aún no está productiva. El primer site que recibirá esta nueva funcionalidad es México y la fecha prevista es junio de 2024.

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.
El primer cambio significativo está en el array de variations en /items, que dejará de ser enviado en el POST y en el response de los nuevos items estará vacío. Este ajuste modifica la lógica de publicación, abriendo nuevas posibilidades y enfoques estratégicos.



Conceptos iniciales

Antes de realizar la comparación y explicación de los cambios, es importante comprender algunos conceptos:
1 - Item es la publicación que el comprador visualiza y que contiene información sobre la condición de venta, precio y total de stock. Se representa mediante el campo item_id y se genera cuando el integrador realiza un POST en el recurso /items.
2 - User Product: es la entidad lógica que representa el ítem físico. Los ítems están asociados a su user product, representado por el campo user_product_id, generado automáticamente por MELI. Un user product puede tener más de un ítem asociado. En el futuro va permitir trabajar múltiples stocks.
3 - Familia: es el agrupador de variaciones, asignado por MELI según los atributos de los ítems publicados. Los ítems que representan variaciones de un mismo producto recibirán en su respectivo user product el campo family_id con el mismo valor.



Comparativo publicar


Hoy

1 - La publicación de variantes se realiza a través del array variations y el integrador/vendedor especifica únicamente el stock y algunos atributos de las variaciones.
2 - El precio se establece en la raíz de la publicación y es el mismo para todas las variantes..
3 - El agrupamiento de las variaciones se hace según el ítem, y cada variación de este ítem tiene su propio variation_id.



Ejemplo:

curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: $ACCESS_TOKEN' \
--data '{
  "title": "Teste - Não ofertar",
  "category_id": "MLB275575",
  "price": 100,
  "currency_id": "BRL",
  "available_quantity": 10,
  "buying_mode": "buy_it_now",
  "listing_type_id": "gold_special",
  "condition": "new",
  "video_id": "YOUTUBE_ID_HERE",
  "sale_terms":[
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantía",
            "value_id": "2230280",
            "value_name": "Garantía del vendedor"
        },
        {
            "id": "WARRANTY_TIME",
            "name": "Tiempo de garantía",
            "value_id": null,
            "value_name": "90 días"
        }
    ],
  "variations": [
      {
        "attribute_combinations": [
                {
                    "id": "COLOR",
                    "name": "Cor",
                    "value_id": "52049",
                    "value_name": "Preto",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "52049",
                            "name": "Preto",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                },
                {
                    "id": "SIZE",
                    "name": "Tamanho",
                    "value_id": "3189128",
                    "value_name": "33",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "3189128",
                            "name": "33",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                }
            ],
        "picture_ids": [
            "http://http2.mlstatic.com/D_690796-MLB70039699580_062023-O.jpg"
          ],
        "price": 100,
        "available_quantity": 1
      },
{
        "attribute_combinations": [
                {
                    "id": "COLOR",
                    "name": "Cor",
                    "value_id": "52005",
                    "value_name": "Marrom",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "52005",
                            "name": "Marrom",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                },
                {
                    "id": "SIZE",
                    "name": "Tamanho",
                    "value_id": "3189128",
                    "value_name": "33",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "3189128",
                            "name": "33",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                }
            ],
        "picture_ids": [
            "https://http2.mlstatic.com/D_769119-MLB70059370475_062023-O.jpg"
          ],
        "price": 100,
        "available_quantity": 1
      }      
],
"shipping": {
        "mode": "me2",
        "methods": [],
        "tags": [],
        "dimensions": null,
        "local_pick_up": false,
        "free_shipping": true,
        "logistic_type": "drop_off",
        "store_pick_up": false
    },
"attributes": [
        {
            "id": "BRAND",
            "name": "Marca",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        },
        {
            "id": "GENDER",
            "name": "Gênero",
            "value_id": "339666",
            "value_name": "Masculino",
            "value_struct": null,
            "values": [
                {
                    "id": "339666",
                    "name": "Masculino",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "ITEM_CONDITION",
            "name": "Condição do item",
            "value_id": "2230284",
            "value_name": "Novo",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "Novo",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "MODEL",
            "name": "Modelo",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        }
]
}
'

Después

1 - El array de variations no debe ser enviado y cada variación se convierte en un ítem independiente, lo que implica realizar un POST a /ítems por cada variación;


Ejemplos:


Variación 1

curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '
{
  "title": "Teste - Não ofertar",
  "category_id": "MLB275575",
  "price": 100,
  "currency_id": "BRL",
  "available_quantity": 10,
  "buying_mode": "buy_it_now",
  "listing_type_id": "gold_special",
  "condition": "new",
  "pictures":[
     {
        "source":"http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg"
     }
  ],
  "sale_terms":[
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantía",
            "value_id": "2230280",
            "value_name": "Garantía del vendedor"
        },
        {
            "id": "WARRANTY_TIME",
            "name": "Tiempo de garantía",
            "value_id": null,
            "value_name": "90 días"
        }
    ],
"shipping": {
        "mode": "me2",
        "methods": [],
        "tags": [],
        "dimensions": null,
        "local_pick_up": false,
        "free_shipping": true,
        "logistic_type": "drop_off",
        "store_pick_up": false
    },
"attributes": [
        {
            "id": "BRAND",
            "name": "Marca",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        },
        {
            "id": "GENDER",
            "name": "Gênero",
            "value_id": "339666",
            "value_name": "Masculino",
            "value_struct": null,
            "values": [
                {
                    "id": "339666",
                    "name": "Masculino",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "ITEM_CONDITION",
            "name": "Condição do item",
            "value_id": "2230284",
            "value_name": "Novo",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "Novo",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "MODEL",
            "name": "Modelo",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        },
        {
                    "id": "COLOR",
                    "name": "Cor",
                    "value_id": "52049",
                    "value_name": "Preto",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "52049",
                            "name": "Preto",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                },
                {
                    "id": "SIZE",
                    "name": "Tamanho",
                    "value_id": "3189128",
                    "value_name": "33",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "3189128",
                            "name": "33",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                }
]
}'

Variación 2

curl --location 'https://api.mercadolibre.com/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '{
  "title": "Teste - Não ofertar",
  "category_id": "MLB275575",
  "price": 100,
  "currency_id": "BRL",
  "available_quantity": 10,
  "buying_mode": "buy_it_now",
  "listing_type_id": "gold_special",
  "condition": "new",
  "pictures":[
     {
        "source":"https://http2.mlstatic.com/D_769119-MLB70059370475_062023-O.jpg"
     }
  ],
  "sale_terms":[
        {
            "id": "WARRANTY_TYPE",
            "name": "Tipo de garantía",
            "value_id": "2230280",
            "value_name": "Garantía del vendedor"
        },
        {
            "id": "WARRANTY_TIME",
            "name": "Tiempo de garantía",
            "value_id": null,
            "value_name": "90 días"
        }
    ],
"shipping": {
        "mode": "me2",
        "methods": [],
        "tags": [],
        "dimensions": null,
        "local_pick_up": false,
        "free_shipping": true,
        "logistic_type": "drop_off",
        "store_pick_up": false
    },
"attributes": [
        {
            "id": "BRAND",
            "name": "Marca",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        },
        {
            "id": "GENDER",
            "name": "Gênero",
            "value_id": "339666",
            "value_name": "Masculino",
            "value_struct": null,
            "values": [
                {
                    "id": "339666",
                    "name": "Masculino",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "ITEM_CONDITION",
            "name": "Condição do item",
            "value_id": "2230284",
            "value_name": "Novo",
            "value_struct": null,
            "values": [
                {
                    "id": "2230284",
                    "name": "Novo",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "list"
        },
        {
            "id": "MODEL",
            "name": "Modelo",
            "value_id": null,
            "value_name": "Teste",
            "value_struct": null,
            "values": [
                {
                    "id": null,
                    "name": "Teste",
                    "struct": null,
                    "source": 6808261514773724
                }
            ],
            "attribute_group_id": "OTHERS",
            "attribute_group_name": "Outros",
            "source": 6808261514773724,
            "value_type": "string"
        },
         {
                    "id": "COLOR",
                    "name": "Cor",
                    "value_id": "52005",
                    "value_name": "Marrom",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "52005",
                            "name": "Marrom",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                },
                {
                    "id": "SIZE",
                    "name": "Tamanho",
                    "value_id": "3189128",
                    "value_name": "33",
                    "value_struct": null,
                    "values": [
                        {
                            "id": "3189128",
                            "name": "33",
                            "struct": null,
                            "source": 6808261514773724
                        }
                    ],
                    "source": 6808261514773724,
                    "value_type": "string"
                }
            ]
}
'

2 - El precio y las condiciones comerciales pueden determinarse según cada ítem de la familia. Es importante tener en cuenta que ahora cada variación corresponde a un ítem. Para esto, te recomendamos consultar la sección Precios de productos.
3 - Los ítems se agrupan en familias según atributos similares como marca, modelo etc. Estos grupos reciben el mismo valor en el campo family_id como identificador de agrupación en su user product. Hay que considerar que para que Mercado Libre considere un ítem como variación, el título debe ser el mismo que en las otras variaciones



Cómo identificar las familias

Dando continuidad a la información proporcionada en los tópicos anteriores, donde se explicó el nuevo flujo de publicación y la agrupación de los nuevos ítems para representar las variaciones según el concepto de familias, presentaremos ahora como identificar los user products de una família y como acceder a lista de ítems que ellos representan.

Importante:
Los recursos de user products aún no están disponibles para prueba.

Existen 2 formas de identificar los ítems que pertenecen a una familia.



Opción 1

  1. Es necesario que la aplicación esté suscrita en el nuevo tópico de notificaciones de familia.
  2. Cuando creamos o cambiamos algo en una familia, se genera una notificación indicando el family_id de la acción.

    {
      "msg": {
        “family_id”:4719173094241697799',
        “site_id”:“MLA”,
        “user_id”:1234
        }
      },

    Este identificador nos permite consultar qué user products están asociados a familia y así identificar sus publicaciones.



  3. Para identificar los user_product_id de una familia, es necesario realizar la siguiente llamada:
  4. Ejemplo:

    curl --location 'https://api.mercadolibre.com/sites/$SITE_ID/user-products-families/$FAMILY_ID' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

    Llamada:

    curl --location 'https://api.mercadolibre.com/sites/MLB/user-products-families/4719173094241697799' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

    Respuesta:

    {
      "user_products_ids": [
        "MLBU205541999",
        "MLBU206642488"
      ]
    }
  5. Para obtener los ítem_ids relacionados a un user product podrá hacer la siguiente llamada:

Ejemplo

curl --location 'https://api.mercadolibre.com/users/$SELLER_ID/items/search?user_product_id=$USER_PRODUCT_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Llamada:

curl --location 'https://api.mercadolibre.com/users/1403810308/items/search?user_product_id=MLBU206642488' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
    "seller_id": "1403810308",
    "results": [
        "MLB2012058964",
        "MLB2012058757"
    ],
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 2
    },
    "query": null,
    "orders": [
        {
            "id": "stop_time_asc",
            "name": "Order by stop time ascending"
        }
    ],
    "available_orders": [...]
}

Opión 2

Todo ítem nuevo va estar asociado a un user product.


  1. Es posible obtener esta información el la respuesta del POST a /items o después de publicado haciendo una consulta al ítem.
  2. Con el user_product_id debes hacer una consulta al recurso /user-products para identificar el family_id atribuído.
  3. Llamada:

    curl --location 'https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID' \
    --header 'Authorization: Bearer $ACCESS_TOCKEN'

    Ejemplo:

    curl --location 'https://api.mercadolibre.com/user-products/$USER_PRODUCT_ID' \
    --header 'Authorization: Bearer $MLBU22012'

    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,
        "tags": [
            "test"
        ],
        "date_created": "2023-02-13T02:46:20.528+0000",
        "last_updated": "2023-02-13T02:46:20.528+0000"
    }
  4. En la respuesta vas a encontrar el campo family_id. Puedes utilizar la información en el recurso /user-products-families para identificar los otros user products de esta familia, como presentamos en el paso 2 de la opción 1.

Alteraciones en los ítems

Para realizar alteraciones en los ítems, deben seguir haciendo PUT al recurso /items.


Puntos Importantes

El item puede cambiar de família:
Las alteraciones en los atributos de los ítems de una familia pueden hacer con que dichos ítems salgan de la familia, por ejemplo, al cambiar marca, modelo, etc. Los atributos que son similares que relacionan el ítem con la familia pueden modificarse, pero tanto el integrador como el vendedor deben tener en cuenta que estos ítems saldrán de la familia actual.
El user_product_id del item puede cambiar:
Hay casos muy específicos en que esto puede pasar. Cambios en el ítem que hagan con que el tenga la infos relacionadas a otro user product, pueden hacer con que el sea vinculado a este otro user product.

Flujos que no son impactados por este desarrollo

Moda

Las modificaciones en el proceso de publicación no afectan por el momento el funcionamiento de los recursos de moda. Sin embargo, es crucial vincular la Guía de Talles a cada ítem de una misma familia. Para más información consulta la sección Gestionar guía de talles.



Promociones

El flujo de promociones no se verá afectado por el nuevo funcionamiento. Podrás seguir la documentación teniendo en cuenta que cada ítem de una misma familia se comportará de manera independiente con sus propias promociones.



Órdenes y envíos

No hay impactos que requieran desarrollo en esta área. Continuaremos enviando el item_id de cada artículo vendido, que puede ser una variación o no. Sin embargo, ten en cuenta que cada variación tendrá su propio item_id además de user_product_id.