Preço por variação

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

Teremos 2 tipos de usuários, os que poderão publicar com o modelo anterior e os que poderão começar a publicar com o novo modelo de User Products (ambos modelos coexistirão). Esses sellers poderão ser identificados através da tag "user_product_seller" na API de users.

Chamada:

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

Resposta:

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

Considerações

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"

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

Modificação de itens

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.

Modificar família

Você pode modificar o family_name através do seguinte recurso, lembrando que só pode ser modificado se os itens associados ao user_product que você deseja modificar ainda não tenham vendas.

Chamada:

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

Resposta:

{
   "family_name": "Novo family name"
}

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. Em caso de que modifiquem os atributos do item, tal como o family_name, o user_product_id continua sendo o mesmo. Somente atualizarão os atributos editados de todas as condições de venda conectadas a este mesmo User Products.

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

Notificações de famílias

Notificaremos o vendedor quando uma família for alterada, isso se deve ao fato de que um User Product experimenta uma mudança em algum dos atributos comprometidos no cálculo da família, o que faz com que o produto migre para outra família.

A mensagem de notificação conterá a chave family_id com o ID da família afetada.

No caso de a família ter sido modificada, a mensagem será enviada com o ID da nova família de destino. Se uma nova família for criada (como resultado da criação de um User Product), o ID da nova família será incluído na notificação. Finalmente, se a família original for eliminada devido à migração do User Product para outra família, o ID da família anterior será enviado na notificação.

Exemplo:

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

Elegibilidade de itens - UPTIN

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

Os vendedores poderão migrar seus itens para o novo modelo de preço por variação, introduzindo o conceito de UPtin para se referir ao processo de migrar um item do modelo anterior para o novo modelo de publicação de produtos do usuário.

Considerações de elegibilidade

Um item só será elegível para UPtin se:

• O atributo "user_product_id" do item original for diferente de nulo.
• Não existirem User Products duplicados por variação.
• O item original tiver variações.

Para consultar a elegibilidade dos itens antigos para o novo formato de User Products, você deve usar o seguinte recurso:

Chamada:

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

Exemplo:

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

Resposta:

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

Os atributos indicam:

is_valid: true, indica que o item é candidato a realizar UPtin. E false para casos que não são candidatos.

Migração de itens

A migração consistirá em criar um novo item para cada variação que contém o item original. Este processo será realizado de maneira assíncrona, portanto, enquanto a migração não estiver concluída, o item original permanecerá ativo e o vendedor continuará vendendo com esse item até que todos os itens das variações originais sejam criados e ativados.

Após a conclusão da migração, o item original será finalizado (status = "closed"), todos os itens criados a partir de un UPtin terão a tag variations_migration, e enviaremos uma notificação no tópico de itens em cada caso (itens novos e item fechado).

Para executar o UPtin, você deve usar o seguinte recurso, indicando o item a ser migrado no body request (você deve fazer uma solicitação para cada item a ser migrado).

Chamada:

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

Resposta:

204

Status de migração

Para que você possa conhecer o status de migração de cada item, suas variantes e os novos itens criados, será possível realizar isso através do seguinte recurso:

Chamada:

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

Exemplo:

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

Resposta:

{
   "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 resposta:

• Status 200 e atributo date_created é null, quer dizer que a migração ainda está em processo.
• Status 200 e atributo date_created é diferente de null, quer dizer que a migração foi concluída com sucesso e mostra o timestamp de finalização.
• Status 404 - não foi possível realizar a migração.

Ativação de testes

Poderá solicitar a ativação em sua conta de testes através deste formulário. Lembrando que, temos ambiente de testes somente em contas da Argentina.

Siguiente: Estoque distribuído.