Mercado Livre - Editor e atualização de dados da família
Para otimizar a gestão de estoque e anúncios no Mercado Livre, o sistema opera com o conceito de Família de Produtos (user_products).
Quando um produto possui variações, como diferentes tamanhos, cores ou voltagens, esses itens são agrupados sob um identificador único chamado family_id. Isso permite centralizar a gestão e atualizar características essenciais de todas as variantes de uma só vez.
Como funciona a edição na prática
Alterações Coletivas (Nível Familiar)
Modificações em dados estruturais são replicadas simultaneamente para todos os membros da família. Isso inclui:
- Nome da Família (family_name)
- Categoria/Domínio (domain_id)
- Atributos-chave e especificações customizadas compartilhadas.
Importante: para atualizar um atributo estrutural, a alteração deve obrigatoriamente englobar todos os produtos da família na mesma requisição. Se um único item for deixado de fora, o sistema recusará a atualização por dados incompletos.
Exceção Individual
É permitido alterar o valor de um atributo para uma variante de forma isolada, desde que essa mudança não quebre as regras estruturais da família.
Impactos e consequências de alterações críticas
Modificações na estrutura de uma família geram ações automáticas no ecossistema do Mercado Livre. Fique atento aos comportamentos do sistema:
- Mudar o Nome da Família (family_name): O título do anúncio será recalculado automaticamente e replicado para todas as condições de venda ativas daquele produto. O sistema também reavaliará o family_id, podendo mover o produto para outra família.
- Mudar o Título do Item Diretamente: O sistema não permite esta ação e retornará erro (Bad Request). O título deve ser sempre derivado das regras e atributos da família.
- Mudança Automática de Família: Alterar atributos profundos (como marca ou modelo) fará o sistema entender que o item mudou de natureza, removendo-o automaticamente da família atual.
- O ID do Produto muda? Não. O código identificador (user_product_id) permanece imutável, mesmo que seus atributos e famílias sofram alterações.
Coexistência de Modelos: Novo vs. Velho
Nem todos os produtos da base estão no novo formato. Para identificar o cenário do lojista, verifique as tags:
- Modelo Novo (Estruturado): Os itens que já operam neste formato possuem a tag "user_product_listing" no sistema.
- Modelo Tradicional: Produtos sem variações no catálogo continuam seguindo o fluxo antigo do marketplace, sem qualquer impacto.
Guia rápido de erros (Códigos de rejeição da API)
Se o time de N3 enviar uma análise ou você identificar falhas nos logs de sincronização, estes são os motivos mais comuns para o sistema rejeitar a edição:
Cenário de Erro |
Causa Provável |
Como corrigir |
|---|---|---|
| Falta de modificações | O payload foi enviado sem nenhuma alteração real em relação aos dados atuais. | Validar se o lojista realmente alterou algum dado antes de salvar. |
| Campos obrigatórios vazios | Envio de family_name, domain_id ou lista de produtos como nulo ou vazio. | Preencher todos os campos mandatórios da estrutura. |
| Família Incompleta (Mais Comum) | Tentativa de atualizar dados estruturais sem enviar todos os produtos que pertencem àquela família juntos. | Garantir que todos os SKUs do agrupamento constem na mesma requisição. |
| Atributo Duplicado | A mesma especificação técnica foi repetida no mesmo produto ou nas regras gerais. | Remover a duplicidade de atributos no payload. |
| Colisão de Família | Após a atualização, o resultado final do produto ficou idêntico a outra família já existente. | Ajustar os atributos para evitar a criação de famílias duplicadas no marketplace. |
