Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
User Products
No modelo anterior de publicações de um vendedor, era possível criar variações que agrupavam diferentes opções do mesmo produto, como uma camisa em várias cores ou tamanhos. Essas variações permitiam oferecer produtos relacionados dentro da mesma publicação. No entanto, esse modelo tinha várias limitações:
- Não era possível estabelecer diferentes preços por variação.
- Não é possível configurar diferentes formas de entrega por variantes.
- Não era possível aplicar promoções ou parcelamento específico por variação.
Nosso objetivo é adotar um novo modelo que resolva esses problemas e unifique a experiência, desacoplando as condições de venda para permitir diferenças em cada variação e assim expandir as publicações.
A partir disso, surge a ideia de criar "User Products" (Produtos de Usuário), onde as iniciativas a serem trabalhadas serão:
Esse enfoque permitirá oferecer uma maior flexibilidade na configuração das publicações, permitindo preços e gestão de estoque específicos para cada variação, o que melhorará a experiência do comprador e a eficiência nas operações de venda.
Conceitos importantes
Para compreender o modelo de User Product (UP), é fundamental considerar os seguintes conceitos:
- Item:
- É a representação da publicação de um produto que um comprador visualiza na plataforma.
- Contém informações relativas às condições de venda (preço, parcelas, etc.).
- Cada item possui um identificador único (item_id) associado.
- User Product (UP):
- Representa um produto físico que um vendedor possui e oferta através da plataforma.
- Um UP descreve o produto da forma mais específica possível (nível de variação).
- Cada UP possui um identificador único (user_product_id) atribuído automaticamente pelo sistema.
- Pode estar associado a um ou mais ítens. Exemplo: um iPhone vermelho (o UP) pode estar no item1 em 3 parcelas e no item2 com outro preço diferente.
- Todo UP poderá ser visualizado no Mercado Livre por meio de uma User Products Page (UPP).
- Família:
- É autogerada com base nas informações dos produtos.
- Cada UP está relacionado a uma família (family_id), e cada família agrupa vários UPs.
- Os itens da mesma família terão o mesmo family_name e serão representados como pickers diferentes na UPP. Os pickers são as opções oferecidas a um comprador para adquirir um produto, incluindo diferentes condições de venda e atributos, como a cor.
- A modificação dos itens através do PUT ao recurso /items, que se refere às características do User Product, será replicada pelo Mercado Livre de forma assíncrona em todos os itens associados ao mesmo User Product. Os campos do item que são sincronizados são:
- Para itens de moda, a tabela de medidas será compartilhada pela variação (User products) e suas condições de vendas (ítens).
A seguir, para exemplificar os conceitos mencionados anteriormente, apresentamos uma comparação entre uma publicação no modelo anterior vs o endgame com User Products.
Baseado no novo modelo, apresentamos um exemplo para uma família e sua composição tanto em User Products (UP) quanto em seus itens e condições de venda:
FAQs
Preço por variação
Que tipo de integradores devem adaptar seus desenvolvimentos a esta iniciativa?
A iniciativa de Preço por variação e UPtin aplica a todos os integradores que publicam, sincronizam ou inclusive mostram uma lista de publicações para os vendedores. A iniciativa de Stock Distribuído e Multi Origem aplica para todos os vendedores que publicam, sincronizam ou toman informação das vendas e envios.
Que impacto terei em caso de não implementar a iniciativa?
Uma vez que os vendedores sejan ativados para começar a publicar no novo modelo de User Products, caso o integrador não esteja adaptado,não será possível publicar com o modelo anterior (informando title e array de variations).
Para os integradores que sincronizam ítens, atualizam stock, preço, o guardam em sua base de dados informação sobre os itens, devem ter em conta a nova estrutura de alteração de stock (a nível de UP) e além disso, receber notificações de alterações pela migração de ítens para manter a consistência de informação em sua base.
Finalmente, para os integradores que listam publicações, devem considerar atualizar seu front para adaptar a proposta de valor que tem o Mercado Livre com esta iniciativa. Ou seja, agrupar os ítens por família, por user product e atém disso (em casos de publicar ou modificar) permitir que se estabeleçam diferentes condições de venda para cada variação.
Como posso identificar os itens que já estão sob o novo modelo de UP?
Será posível identificar os ítens no novo modelo de User Products, através de 2 coisas: a tag "user_product_listing" ou identificando no ítem o atributo family_name diferente de null.
Como posso testar o fluxo de User Products?
Caso seja necessário testar os fluxos de User Products, será necessário solicitar através deste formulário. Cada 15 dias, ativaremos estes novos usuários. Vale lembrar que o cenário de testes será habilitado unicamente para Argentina (deverão criar contas de teste neste site).
Todos os vendedores serão habilitados para trabalhar com o novo modelo de UP?
No endgame, todos os vendedores serão habilitados para publicar no novo modelo de User Products. A partir de outubro os sellers serão habilitados de maneira progressiva até chegar a 100% de sellers.
Como posso identificar os sellers que já se encontram no nuevo modelo de UP?
Através da tag "user_product_seller."
Todos os ítens contarão con user_product_id, family_id e family_name?
- Antes da ativação da tag "user_product_seller": Os Live Listing contarão com user_product_id e não terão family_name. A relação de user_product_id e item_id será 1:1.
- Posterior a ativação da tag "user_product_seller": se realizará um processo de unificação para ítens mono-variantes e sem variantes, com a finalidade de agrupar os ítens que deverão pertencer ao mesmo user_product_id, permitindo que um user_product_id esteja associado a 1 ou mais ítens. Posterior a unificação, os ítens contarão com o atributo family_name.
- Quando o vendedor decide realizar a migração de um ítem multivariante ao novo modelo (UPtin). Neste caso, os novos ítens gerados estarão associados ao mesmo user_product_id e também contarão com family_name.
Até quando o vendedor poderá publicar no modelo anterior?
Até a ativação da tag "user_product_seller". A partir da activação, os novos ítens deverão ser criados no novo modelo.
Existe algum endpoint para listar todas as familias de um vendedor?
Não, atualmente não existe.
Como posso obter todos os itens que correspondem a uma mesma família?
Realizando as seguintes requisições:
- GET a /items para obter o user_product_id
- GET a /user-products/$USER_PRODUCT_ID para obter o family_id
- GET a /sites/$SITE_ID/user-products-families/$FAMILY_ID para obter todos os User Products associados a uma família
É possível atualizar o family_name?
Sim, apenas quando o item ainda não tiver vendas. Tenha em conta que em casos de que o ítem esteja associado a um UP com vários ítems, será possível atualizar o family_name e sincronizará com todos os ítens deste UP.
Ao alterar a condição de venda de uma família, será alterado seu family_name?
Não deveria ser alterado, já que o family_name não está relacionado com as condições de venda (por exemplo, preço e tipo de publicação).
O family_name será gerenciado pelo integrador? Ou seja Meli não vai alterar o valor deste campo?
Sim, será responsabilidade do vendedor/integrador. Somente no caso de UPtin, o Mercado Livre criará o family_name do anúncio.
Posso publicar com atributos tipo custom em User products?
Sim, é possível publicar adicionando o atributo, exemplo:
{
"attributes": [
{
"name": "my-custom-attribute-name",
"value_name":"my-custom-attribute-value"
}
]
}
O recurso /categories continuará funcionando da mesma forma para que possamos consultar os atributos e suas tags? Por exemplo, allow_variations e variation_attribute.
Sim, inclusive, você poderá tomar como referência (não regra) esses atributos para entender qual será o atributo levado para a completar do family_name da publicação.
Será possível enviar o array de variations após a ativação de um seller no novo modelo de UP?
Não, não será possível enviar o array, pois cada uma das variações será uma condição de venda (itens diferentes).
Que atributos são sincronizáveis a nível UP?
Name (title do item)
Family Name (family_name do item)
Site Id (site_id do item)
User Id (seller_id do item)
Domain Id (domain_id do item)
Catalog Product Id (catalog_product_id do item)
Family Id (próprio do user_product)
Date Created (próprio do user_product)
Last Updated (próprio do user_product)
Attributes (atributos do item + attributes_combination em caso de que o user product seja gerado a partir de uma variação de ítem)
Pictures (pictures do item)
Thumbnail (thumbnail do item)
Tags (próprio do user_product)
UPtin
Os itens que estão no modelo anterior migrarão automaticamente para o novo modelo?
Não, os itens só poderão ser migrados mediante solicitação do seller, seja pelo front do Mercado Livre ou pelo seu integrador.
Quando o vendedor migre uma publicação com 3 variantes do modelo atual ao modelo User Products. Como será enviada a notificação de criação?
Receberá uma notificação por cada ítem criado através do tópico de ítems. O ítem antigo ficará com o status closed e cada publicação nova criada terá a tag “variations_migration_uptin”.
O que acontecerá com as informações de vendas das publicações antigas?
As informações de vendas permanecerão exatamente iguais, não perderão o histórico.
Estoque distribuído e multi origem
Poderá enviar stock para todas as condiç˜ões de venda de uma só vez?
Sim, deverão usar o recurso de estoque distribuído, que permite enviar o stock diretamente ao UP, e sincronizará a todas as condições de vendas.
O mesmo anúncio poderá estar em mais de um armazém?
Sim, pode estar em mais de 1 armazem. O novo POST permite indicar o stock que tem o anúncio em cada armazém ou loja. O stock estará a nivel de UP, e o UP pode ter diferentes stock por lojas, ou seja, os anúncios/condições de venda associados a esse UP terão o mesmo stock.
Se poderá distribuir o stock para publicações que se encontram no modelo anterior?
Sim, uma vez que a publicação conta com user_product_id é possível fazer a gestão de stock através do user product. Adicionalmente, os vendedores com a tag "warehouse_management" poderão distribuir o stock por lojas.
Ajude-nos a melhorar
Recomendamos complementar esta leitura com a documentação do nosso Devsite, inclusive as próximas documentaç˜ões. No entanto, caso tenha mais perguntas referentes a User Products, você pode enviar suas dúvidas através deste formulário, isso nos ajudará a complementar este documento.
Siguiente: Preço por variação.