Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 14/03/2024

Preço por variação

Importante:
Esta iniciativa ainda não é produtiva. O primeiro sítio a receber esta nova funcionalidade é o México e a data prevista é junho de 2024.

A iniciativa de preço por variação tem cómo objetivo proporcionar ao vendedor a capacidade de oferecer diferentes condições de venda para as variações de um mesmo produto, o que lhe permite aplicar suas estratégias de venda de maneira mais flexível e escálavel.
A primeira mudança siginificativa está no array de variationsem /items, que deixará de ser enviado no post e a resposta dos novos itens estará vazia. Este ajuste modifica a lógica de anunciar, abrindo novas possibilidades e focos estratégicos.



Conceitos iniciais

Antes de realizar a comparação e explicação das mudnças, é importante compreender alguns conceitos:
1 - Item é o anúncio que o comprador visualiza, contém informação sobre a condição de venda, preço e total do estoque. É apresentado mediante o campo item_id e gerado quando o integrador realiza um POST no recurso /items.
2 - User Product: é a entidade lógica que representa o item físico. Os itens estão assoadiso ao seu user product, representado pelo campo user_product_id, gerado automáticamente pelo MELI. Um user product pode ter mais de um item associado. No futuro permitirá trabalhar com múltiplos estoques.
3 - Familia: é o agrupador de variações, atribuído pelo MELI segundo os atributos dos itens anunciados. Os itens que representam variações de um mesmo produto receberão em seu respectivo user product o campo family_id com o mesmo valor.



Comparativo anunciar


Hoje

1 - O anúncio de variações é realizado através do array variações e o integrador/vendedor específica apenas o estoque e alguns atributos das variações.
2 - O preço se estabelece na raíz do anúncio e é o mesmo para todas as variações.
3 - O agrupamento das variações é feito segundo o item, e cada variação deste item tem seu próprio variation_id.



Exemplo:

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"
        }
]
}
'

Depois

1 - O array de variations não deve ser enviado, e cada variação será convertida em um item indepenten, o que implica realizar um POST a /items para cada variação.


Exemplos:


Variação 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"
                }
]
}'

Variação 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 - O preço e as condições comerciais podem ser determinadas segundo cada item da família. É importante considerar que agora cada variação corresponde a um item. Para isso, recomendamos que use a documentação de Preços de produtos.
3 - Os itens são agrupados em famílias segundo atributos similares como marca, modelo, etc. Estes grupos recebem o mesmo valor no campo family_id como identificador de agrupamento em seu user product. Deve-se considerar que para o que o MELI considere um item cómo variação, o título deve ser o mesmo que o das outras variações.



Como identificar as famílias

Continuando a informação proporcionada nos tópicos anterior, onde foi explicado o novo fluxo de anúncio e o agrupamento de novos itens para representar as variações segundo o conceito de famílias, apresentamos agora cómo identificar o user products de uma famíla, e como acessar a lista de itens que eles representam.


Importante:
Os recursos do user products ainda não estão disponíveis para teste.

Existem duas formas de identificar os itens que pertencem à uma famíla.



Opção 1

  1. O aplicativo precisa estar inscrito no novo tópico de notificações de famílias.
  2. Quando criamos ou alteramos algo em uma família, creamos o cambiamos algo en una familia, se é gerada uma notificação indicando o family_id da ação.

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

    Este identificador nos permite consultar quais user products estão associados à famía, e assim identificar seus anúncios



  3. Para identificar os user_product_id de uma famía, é necessário realizar a seguinte chamada.
  4. Exemplo:

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

    Chamada:

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

    Resposta:

    {
      "user_products_ids": [
        "MLBU205541999",
        "MLBU206642488"
      ]
    }
  5. Para obter os ítem_ids relacionados a um user product você poderá fazer a seguinte chamada.

Exemplo

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

Chamada:

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

Resposta:

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

Opção 2

Todo item novo estará associado a um user product.


  1. É possível obter informação da resposta do POST a /items ou depois de anunciado realizando uma consulta ao item.
  2. Com o user_product_id você deve fazer uma consulta ao recurso /user-products para identificar o family_id atribuído.
  3. Chamada:

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

    Exemplo:

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

    Resposta:

    {
        "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. Na resposta você irá encontrar o campo family_id, e poderá utilizar a informação no recurso /user-products-families para identificar os outros user products desta família, como apresentamos no passo 2 da opção 1.

Alterações nos itens

Para realizar alterações nos itens, realize PUT ao recurso /items.


Pontos importantes

O item pode mudar de família:
As alterações nos atributos dos itens de uma família podem fazer com que ditos itens saiam de uma família, por exemplo, ao alterar marca, modelo, etc. Os atributos que são similares que relacionam o item com a família podems er modificados, mas tanto integradores cómo o vendedor devem considerar que estes itens irão sair da família atual.
O user_product_id do item pode alterar:
Há casos muito específicos em que isto poderá acontecer. Alterações no item que façam com que ele tenha as informações relacionadas a ooutro user product, podem fazer com que seja vinculado a outro user product.

Fluxos que não são impactados por este desenvolviimento

Moda

As modificações o processo de anunciar não impactam por enquanto o funcionamento dos recursos de moda. No entando, é importante vincular a tabela de medidas a cada item de uma mesma família. Para mais informações, consulte a seção Gerenciar tabelas de medidas.



Promoções

O fluxo de promoções não será impactado pelo novo funcionamento. Você pode seguir a documentação considerando que cada item de uma mesma família se comportará de maneira independente com suas próprias promoções.



Orders e envios

Não há impactos que precisem de desenvolvimento nesta área. Continuaremos enviando o item_id de cada produto vendido, que pode ser uma variação ou não. No entanto, considere que cada variação terá seu próprio item_id além de user_product_id.