Pular para o conteúdo principal

Introdução

Busque rótulos de status de produtos ("Novo", "Promoção", "Esgotado") para identificar e filtrar itens do catálogo.

Mais informações sobre os status de produtos no painel administrativo do OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 O que este módulo faz?​

O módulo ProductStatuses fornece condições de filtragem adicionais para itens do catálogo juntamente com filtros baseados em atributos. Os Status de Produtos permitem que você crie rótulos personalizados - como "Nova Chegada", "Mais Vendido", "Promoção", "Esgotado" - para identificar, organizar e filtrar produtos em seu catálogo de e-commerce.

Você define os rótulos de status no painel administrativo do OneEntry (Catálogo > Status de Produtos), atribui-os aos produtos e usa este módulo para buscar os status e filtrar produtos por eles. O SDK é somente leitura: você não pode criar status através dele.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { ProductStatuses } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque todos os status e leia seus campos:

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

✨ Conceitos Chave​

O que é um Status de Produto?​

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

  • Nome do Status (localizeInfos) - Nome de exibição localizado (por exemplo, "Nova Chegada", "Promoção")
  • Marcador de Status (identifier) - Identificador único usado para filtragem
  • Flag padrão (isDefault) - Se este é o status padrão
  • Posição (position) - Ordem de exibição

Fluxo de Trabalho do Status de Produto​

1. Create status in admin panel
   (e.g., "New Arrival")
   ↓
2. Assign status to products
   (Select products in admin)
   ↓
3. Fetch statuses via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Display status badges on products
   (Render badges in product listings)
   ↓
5. Filter products by status marker
   (Products.getProducts([{ statusMarker }], langCode))

📋 O que você precisa saber​

Status são criados no painel administrativo​

Você não pode criar status via SDK - eles são criados no painel administrativo do OneEntry (Catálogo > Status de Produtos). Cada status precisa de um Nome (obrigatório) e um Marcador único (obrigatório).

Restrições do Marcador:

  • Apenas letras latinas (a-z, A-Z) e números (0-9)
  • Subtraço (_) e hífen (-) permitidos
  • Sem espaços ou caracteres especiais
  • Deve ser único entre todos os status

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

Um status por produto​

Um produto referencia no máximo um status. O objeto do produto carrega statusIdentifier (o marcador de status, ou null):

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

Filtrando por status​

Para filtrar produtos por status, use o método getProducts(body, langCode, userQuery) do módulo Products. Passe um campo statusMarker dentro do array do corpo IFilterParams para buscar produtos com um status específico.

Validando um marcador​

validateMarker(marker) retorna true se o marcador existir e false caso contrário. Como o SDK não pode criar status, use-o para verificar um marcador antes de referenciá-lo em seu código.

Status vs atributos​

ProductStatuses são diferentes de atributos de produtos:

RecursoProductStatusesAtributos
PropósitoRótulos/identificadores/filtrosPropriedades do produto
Exemplos"Novo", "Promoção", "Destaque"Cor, Tamanho, Material
Por produtoUm statusMuitos atributos
FiltragemSimples (por marcador 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 um status de produto por marcadorBuscar status por identificador
validateMarker()Verificar se um marcador existeValidar marcador antes do uso

❓ Perguntas Comuns (FAQ)​

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

Os status de produtos são rótulos de marketing (Novo, Promoção, Destaque) para filtragem e identificaçã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?​

Não. Um produto referencia no máximo um status, exposto como statusIdentifier (o marcador de status) no objeto do produto.

Como faço para filtrar produtos por status?​

Use o método getProducts(body, langCode, userQuery) do módulo Products. Passe um campo statusMarker dentro do array do corpo IFilterParams para buscar produtos com um status específico.

Como faço para verificar se um marcador de status existe?​

Use validateMarker() - ele retorna true se o marcador existir e false caso contrário. O SDK não pode criar status; os marcadores são definidos no painel administrativo seguindo as convenções de nomenclatura (apenas letras latinas, números, subtraço, hífen).

Posso mudar a ordem dos status exibidos?​

Sim. No painel administrativo, você pode arrastar e soltar os status para reordená-los. Isso afeta o campo position, que determina a ordem de exibição em sua aplicação.

Como faço para adicionar estilos personalizados aos rótulos de status?​

Busque todos os status e, em seguida, mapeie os marcadores de status para classes CSS ou estilos inline em seu código frontend. Aplique esses estilos ao renderizar um rótulo de produto com base no statusIdentifier do produto.

🎓 Melhores Práticas​

  • Use marcadores descritivos - nova_chegada, não status1.
  • Valide antes de referenciar - chame validateMarker() antes de codificar um marcador.
  • Renderize o rótulo de status - mostre o rótulo statusIdentifier do produto nas listagens.
  • Cache os status - eles raramente mudam, então faça cache para desempenho.

🔗 Documentação Relacionada​