Pular para o conteúdo principal

Introdução

🎯 O que este módulo faz?​

O módulo ProductStatuses permite condições de filtragem adicionais para itens do catálogo juntamente com os filtros baseados em atributos existentes. Product Statuses permite que você crie rótulos e filtros personalizados para produtos - como "Nova Chegada", "Mais Vendido", "Promoção", "Fora de Estoque" - para organizar e filtrar produtos em seu catálogo de e-commerce.

Os status servem como mecanismos de filtragem suplementares para itens do catálogo, funcionando em conjunto com a filtragem baseada em atributos para fornecer opções de organização e categorização mais granulares para a gestão de produtos.

Pense nisso como seu sistema de etiquetagem de produtos - você define rótulos de status no painel de administração do OneEntry (Catálogo > Status de Produtos), atribui-os aos produtos e os utiliza para filtrar, marcar e categorizar produtos dinamicamente.

📖 Explicação Simples​

Toda loja de e-commerce precisa destacar produtos especiais:

  • 🆕 Nova Chegada - Produtos recentemente adicionados
  • 🔥 Mais Vendido - Itens populares
  • 💰 Em Promoção - Produtos com desconto
  • ⭐ Destaque - Produtos destacados
  • 📦 Fora de Estoque - Itens indisponíveis
  • 🎁 Edição Limitada - Produtos exclusivos
  • 🚚 Frete Grátis - Produtos com entrega gratuita

Problemas:

  • 🔒 Inflexível - Necessita de alterações de código para adicionar novos status
  • 📊 Difícil de gerenciar - Múltiplos campos booleanos
  • 🔄 Sem reutilização - Não é possível reutilizar a lógica de status
  • 🎨 Inconsistente - Estilos de badge diferentes em todos os lugares

A solução ProductStatuses:

Benefícios:

  • 🔒 Flexível - Adicionar/remover status no painel de administração
  • 📊 Fácil de gerenciar - Definições de status centralizadas
  • 🔄 Reutilizável - Mesmo status para muitos produtos
  • 🎨 Consistente - Renderização uniforme de badges

✨ Conceitos Chave​

O que é um Status de Produto?​

Um Status de Produto é um rótulo/tag personalizado para produtos:

  • Nome do Status - Nome exibido (ex: "Nova Chegada", "Promoção")
  • Marcador de Status - Identificador único para filtragem
  • Cor/Estilo - Representação visual (configurada no admin)
  • Associação de Produto - Quais produtos têm esse status
  • Filtragem - Consultar produtos por status

Fluxo de Trabalho do Status de Produto​

1. Criar status no painel de administração
   (ex: "Nova Chegada")
   ↓
2. Atribuir status aos produtos
   (Selecionar produtos no admin)
   ↓
3. Buscar status via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Exibir badges de status nos produtos
   (Renderizar badges nas listagens de produtos)
   ↓
5. Filtrar produtos por status
   (Products.getProducts({ statusId }))

Por que usar o módulo ProductStatuses?​

BenefícioDescrição
Filtragem FlexívelFiltrar produtos por múltiplos critérios personalizados
Badges DinâmicosMostrar badges visuais sem codificação fixa
Gerenciamento FácilAdicionar/remover status no painel de administração
Rótulos ReutilizáveisAplicar o mesmo status a muitos produtos
Multi-LínguaNomes de status localizados por idioma
Estilo PersonalizadoDefinir cores e estilos por status

📋 O que você precisa saber​

Os Status de Produtos são Criados no Painel de Administração​

Você não pode criar status via SDK - eles são criados no painel de administração do OneEntry:

Painel de Administração do OneEntry → Catálogo → Status de Produtos → Criar Status → Definir Nome/Marcador → Salvar

Processo de Criação:

  • Fornecer um Nome - Designação do status (obrigatório)
  • Fornecer um Marcador - Identificador único (obrigatório, apenas letras/números latinos/'_'/'-' permitidos)
  • Clique em "Criar" para finalizar

Restrições do Marcador:

  • Apenas letras latinas (a-z, A-Z)
  • Números (0-9)
  • Símbolos de sublinhado (_) e hífen (-)
  • Nenhum caractere especial ou espaços permitidos

Gerenciamento de Status:

  • Ver Lista - Tabela com colunas Nome, Marcador e Ações
  • Editar Status - Modificar campos Nome e Marcador
  • Excluir Status - Remover status não utilizados
  • Reordenar - Arrastar e soltar para mudar a ordem de exibição (afeta o campo sortOrder)

O SDK é para buscar status e filtrar produtos, não para criar status.

Atribuição de Status​

Os status são atribuídos aos produtos no painel de administração:

Painel de Administração do OneEntry → Produtos → Editar Produto → Atribuir Status → Salvar

No SDK: Os produtos têm um array statusIds com os IDs de status atribuídos:

const product = await Products.getProductById(123);
console.log(product.statusIds); // [1, 2] - IDs de Status

Filtragem por Status​

Use o ID do status para filtrar produtos

Suporte a Múltiplas Línguas​

Os nomes dos status são automaticamente localizados

💡 Notas Importantes​

Os Status são Criados no Painel de Administração​

Lembre-se: O SDK é para buscar status, não para criá-los.

Para criar/editar status: Use o Painel de Administração do OneEntry.

Interface da Lista de Status​

O painel de administração exibe todos os status em uma tabela com três colunas:

  • Nome - Designação do status
  • Marcador - Identificador único
  • Ações - Operações de editar e excluir, além de reordenação por arrastar e soltar

Validação de Marcador​

Importante: O método validateMarker() ajuda a verificar se um marcador já existe antes de criá-lo/usá-lo.

Restrições do Marcador:

  • Apenas caracteres alfanuméricos latinos (a-z, A-Z, 0-9)
  • Substituto (_) e hífen (-) permitidos
  • Sem espaços ou caracteres especiais
  • Deve ser único entre todos os status

Múltiplos Status por Produto​

Os produtos podem ter múltiplos status simultaneamente (ex: "Nova Chegada" + "Em Promoção")

Status vs Atributos​

ProductStatuses são diferentes de atributos de produto:

RecursoProductStatusesAtributos
PropósitoRótulos/badges/filtrosPropriedades do produto
Exemplos"Novo", "Promoção", "Destaque"Cor, Tamanho, Material
Múltiplos valoresSim (múltiplos status)Sim (múltiplos atributos)
FiltragemSimples (por ID de status)Complexa (intervalos, valores)
Caso de usoRótulos de marketingEspecificações do produto

Melhor prática: Use status para rótulos de marketing, atributos para propriedades do produto.

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getProductStatuses()Obter todos os status de produtosListar todos os status disponíveis
getProductsByStatusMarker()Obter status de produto por marcadorBuscar status por identificador
validateMarker()Verificar se o marcador existeValidar marcador antes do uso

❓ Perguntas Comuns (FAQ)​

Qual é a diferença entre status de produto e atributos de produto?​

Os status de produto são rótulos de marketing (Novo, Promoção, Destaque) para filtragem e marcação, enquanto os atributos são especificações do produto (Cor, Tamanho, Material). Use status para tags promocionais e atributos para propriedades do produto.

Um produto pode ter múltiplos status ao mesmo tempo?​

Sim! Os produtos podem ter múltiplos status simultaneamente. Por exemplo, um produto pode ser tanto "Nova Chegada" quanto "Em Promoção" ao mesmo tempo. O array statusIds no objeto do produto contém todos os IDs de status atribuídos.

Como faço para filtrar produtos por status?​

Use os métodos do módulo Products com filtros de status. Passe o ID ou marcador do status em sua consulta para buscar produtos com status específicos. Você também pode combinar múltiplos filtros de status.

Como valido um marcador antes de criar um status?​

Use o método validateMarker() para verificar se um marcador já existe. Isso ajuda a evitar marcadores duplicados e garante que seu marcador siga as convenções de nomenclatura (apenas letras latinas, números, sublinhado, hífen).

Posso mudar a ordem dos status exibidos?​

Sim! No painel de administração, você pode arrastar e soltar os status para reordená-los. Isso afeta o campo sortOrder e determina a prioridade de exibição em sua aplicação.

Como adiciono estilo personalizado aos badges de status?​

Busque todos os status, crie um mapeamento de marcadores de status para classes CSS ou estilos inline em seu código frontend. Aplique esses estilos ao renderizar badges de produtos com base no array statusIds do produto.

🎓 Melhores Práticas​

  • Use marcadores descritivos - nova_chegada, não status1
  • Defina cores de forma consistente - Use a paleta de cores da marca
  • Limite status ativos - Não sobrecarregue os usuários com muitos badges
  • Mantenha os nomes dos status curtos - "Promoção" é melhor que "Produtos em Promoção"
  • Use status para filtragem - Faça os status filtráveis na interface
  • Cache de status - Eles raramente mudam, faça cache para desempenho
  • Exiba múltiplos status - Mostre todos os badges relevantes nos produtos
  • Use status para ordenação - Ordene pelo status "Destaque" primeiro

Mais informações sobre status de produtos no painel de administração do OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/catalog/product-statuses/

Definição do módulo ProductStatuses​

O módulo ProductStatuses gerencia status que servem como filtros adicionais juntamente com as condições definidas por atributos. Product Statuses permitem condições de filtragem adicionais para itens do catálogo na Plataforma OneEntry, funcionando em conjunto com a filtragem baseada em atributos.


const { ProductStatuses } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​