Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 22/05/2024

Preço por variação

Importante:

A iniciativa estará em produção a partir de julho de 2024, começando na Argentina e se expandindo progressivamente para o Brasil e México. Por enquanto, não teremos um ambiente de testes disponível.

Fornecemos estas informações para que você possa analisá-las e ajustar o backlog de desenvolvimento. Para realizar testes, será necessário simular o fluxo utilizando mocks criados a partir das integrações.

A iniciativa de preço por variação visa proporcionar ao vendedor a capacidade de oferecer diferentes condições de venda para as variações de um mesmo produto, permitindo aplicar suas estratégias de venda de maneira mais flexível e escalável.

Publicar um item

Importante:

Recomendamos começar a analisar o impacto e planejar o backlog para a integração ao publicar itens sem o array de variations nem o campo title.

Você pode começar os testes publicando itens sem variações, mas é fundamental saber que o campo family_name ainda não está disponível. Para evitar falhas na execução, você deve omitir esse campo e adicionar o título da publicação.

A seguir, apresentamos algumas considerações que você deve ter em mente ao querer publicar um item sob o novo modelo de UP.

O novo campo family_name é obrigatório e deve ser preenchido pelo vendedor. Este campo será um nome genérico que abrange os diferentes User Products de uma mesma família. Recomenda-se usar um texto genérico e representativo dos itens, por exemplo:

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

Nota:

O campo family_name será usado para o cálculo do family_id. Para mais detalhes, consulte o detalhe da Família em Conceitos importantes.
O preço e as condições de venda podem variar para cada item publicado. Recomendamos consultar a seção de Preços de Produto.

Além disso, o campo título não deve ser enviado pelo vendedor, pois o Mercado Livre o preencherá automaticamente com as informações do item específico ou do produto. Isso é feito com o objetivo de ter itens mais padronizados,, baseando-se no domínio, atributos, family_name, entre outros.

Como exemplo, estaremos publicando dois itens da mesma família que compartilham: family_name, domínio, condição, seller_id e GTIN.

Primeiro item, na cor 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, na cor vermelha:

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

Exemplo de resposta para a criação de um item:

{
   "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", /*O permalink vai redirecionar para o UPP do 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"
   ]
}

Para realizar mudanças nos itens existentes, você deve continuar executando um PUT no recurso /items. O Mercado Livre replicará essa modificação de maneira assíncrona em todos os itens do mesmo User Product, ao serem modificados atributos compartilhados, como a Tabela de medidas. É importante lembrar que no novo modelo não será permitida a criação de variações por uma chamada POST ou PUT no recurso de itens.

Considerações:

O que acontece se o vendedor modificar o campo family_name?
Se o family_name associado a um item for modificado, o campo de título do item será recalculado e, adicionalmente, a modificação será replicada no User Product, o que desencadeará duas possíveis ações:

O recálculo do family_id, que fará que o User Product seja transferido para outra família, se necessário.
O novo family_name será replicado em todas as condições de venda (itens) associadas ao User Product.

O que acontece se alguém tentar modificar o campo title do item?
É gerado um erro do tipo bad request.

Um item pode mudar de família?
Modificar os atributos dos itens pode fazer com que eles saiam da família atual, por exemplo, ao alterar a marca, modelo, etc.

O user_product_id do item pode mudar?
Não é um campo editável, mas o Mercado Livre poderia relacionar o item com outro User Product como resultado de uma modificação feita pelo vendedor nas informações do item, por exemplo, uma alteração em seus atributos.

Como UP e catálogo conviverão?

Item sem variações e com (catalog_listing = true): O fluxo do catálogo não é impactado, e a PDP é criada com o catalog_product_id. Para mais detalhes, consulte publicações em catálogo.
Item sem variações e com (catalog_listing = false): A UPP (User Products Page) é criada com o item_id e user_product_id.

Consultar um User Product

Você pode obter os detalhes de um User Product fazendo a seguinte chamada:

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

Exemplo de consulta a um UP específico:

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

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, /*Família do UP*/
   "tags": [
       "test"
   ],
   "date_created": "2023-02-13T02:46:20.528+0000",
   "last_updated": "2023-02-13T02:46:20.528+0000"
}

Consultar os User Products de uma família

Você pode obter os User Products associados a uma família específica usando a seguinte chamada:

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

Exemplo do recurso para uma família e um site específicos:

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

Resposta:

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

Busca de itens por User Product

Você pode fazer um search de itens utilizando um filtro pelo 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'

Exemplo para um UP específico:

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

Resposta:

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

Siguiente: Estoque distribuído.