Introdução
Gerencie produtos de e-commerce com catálogos dinâmicos, filtragem e busca.
🎯 O que este módulo faz?
O módulo Products (Catálogo) é um módulo autônomo que permite criar, recuperar, filtrar e gerenciar produtos em sua loja online ou coleções multimídia. Ele fornece ferramentas muito flexíveis para criar catálogos de produtos ou galerias multimídia com recursos poderosos de busca, filtros e organização.
O Catálogo permite criar, fazer upload, editar e filtrar catálogos através de uma interface intuitiva. Além do e-commerce, ele suporta aplicações alternativas como galerias multimídia, demonstrando sua versatilidade como uma ferramenta de gerenciamento de conteúdo.
Pense nisso como seu armazém digital - você gerencia seu inventário de produtos no painel de administração do OneEntry (Catálogo > Produtos), e seu aplicativo busca produtos dinamicamente com busca poderosa, filtros e ordenação.
📖 Explicação Simples
Imagine que você está construindo uma loja online vendendo:
- 👟 Tênis - com tamanhos, cores, preços
- 📱 Eletrônicos - com especificações, imagens, avaliações
- 👕 Roupas - com tamanhos, materiais, variantes
- 📚 Livros - com autores, preços, descrições
✅ Em vez de codificar cada produto, você:
- Adiciona produtos no painel de administração do OneEntry (com todos os detalhes)
- Busca produtos dinamicamente usando este módulo
- Filtra por categoria, faixa de preço, disponibilidade
- Busca produtos por nome ou descrição
- Ordena por preço, data, popularidade
- Atualiza preços/estoque sem precisar redeployar
Exemplo do mundo real:
❌ Without Products Module (hardcoded):
- Add new product → Change code → Deploy
- Change price → Code change → Deploy
- 1000 products = massive code file
✅ With Products Module (dynamic):
- Add new product → Update in admin → Live instantly
- Change price → Update in admin → Live instantly
- 10,000 products = simple API calls
✨ Conceitos Chave
O que é um Produto?
Um produto é um item que você vende, contendo:
- Informações básicas - Nome, descrição, SKU, preço
- Imagens - Fotos do produto, galeria
- Variantes - Tamanhos, cores, opções (ex.: "Camiseta Vermelha Tamanho M")
- Inventário - Quantidade em estoque, disponibilidade
- Atributos personalizados - Quaisquer campos que você definir (marca, material, peso, etc.)
- SEO - Título meta, descrição, palavras-chave
- Status - Ativo, rascunho, fora de estoque
- Localização - Suporte a múltiplas línguas
Estrutura do Produto
Os produtos podem ter diferentes estruturas:
| Tipo | Descrição | Exemplo |
|---|---|---|
| Produto Simples | Item único, sem variantes | Livro, Pôster |
| Produto com Variantes | Múltiplas opções (tamanho, cor) | Camiseta (P/M/G, Vermelha/Azul) |
| Produto Digital | Itens para download | E-book, Software |
| Pacote | Grupo de produtos | Pacote Inicial, Conjunto de Presentes |
Organização do Produto
Os produtos são organizados através de várias características principais:
- Categorias - Organize em seções (As categorias são páginas do tipo Catálogo criadas no módulo Páginas)
- Status dos Produtos - Crie condições de filtragem adicionais além dos filtros de atributos existentes
- Links de Produtos - Estabeleça conexões entre produtos com base em critérios de atributos
- Filtros de Produtos - Busca rápida usando critérios de filtro especificados
- Atributos personalizados - Marca, Tamanho, Cor, Material, etc.
Exemplo de hierarquia:
📁 Electronics
├─ 📱 Smartphones
│ ├─ iPhone 15 Pro
│ └─ Samsung Galaxy S24
└─ 💻 Laptops
├─ MacBook Pro
└─ Dell XPS
📁 Clothing
├─ 👕 T-Shirts
└─ 👖 Jeans
📋 O que você precisa saber
Arquitetura do Catálogo
Importante: As categorias do catálogo são páginas do tipo Catálogo criadas através do módulo Páginas. Você precisa criar as categorias do catálogo primeiro antes de adicionar produtos.
Recursos do Catálogo:
- Aba Produtos - Espaço principal para criar e gerenciar itens do catálogo
- Filtros de Produtos - Busca rápida usando critérios especificados
- Links de Produtos - Conecte produtos com base em critérios de atributos (ex.: todos os telefones pretos)
- Status dos Produtos - Condições de filtragem adicionais para organização
- Upload do Catálogo - Importação em massa de dados do catálogo
- Configurações - Opções de configuração com campos de entrada numéricos
Formas de Obter Produtos
| Método | Quando Usar | Exemplo |
|---|---|---|
| getProducts() | Listar produtos com filtros/busca | Página do catálogo da loja |
| getProductsByPageId() | Produtos de categoria específica (por ID) | Página da categoria |
| getProductsByPageUrl() | Produtos de categoria específica (por URL) | Página da categoria por URL |
| getProductById() | Obter produto único por ID | Página de detalhes do produto |
| getRelatedProductsById() | Obter produtos relacionados/similares | Seção "Você também pode gostar" |
| searchProduct() | Buscar produtos por consulta | Funcionalidade de busca |
Paginação Explicada Simplesmente
Quando você tem 1000 produtos, você não carrega todos de uma vez:
Fórmula de offset: offset = (pageNumber - 1) * limit
Opções de Ordenação
Ordene produtos por diferentes campos:
| sortKey | O que Faz | Exemplo de Uso |
|---|---|---|
| price | Ordenar por preço | Mostrar os mais baratos primeiro |
| date | Ordenar por data de criação | Mostrar os produtos mais novos |
| title | Ordenar alfabeticamente | Lista de produtos de A-Z |
| position | Ordem personalizada (padrão) | Ordem escolhida pelo admin |
| id | Ordenar por ID | Ordenação técnica |
Ordem de ordenação:
- ASC (Crescente) - Baixo para alto (A→Z, 0→9, barato→caro)
- DESC (Decrescente) - Alto para baixo (Z→A, 9→0, caro→barato)
Filtrando Produtos
Use filtros para restringir os resultados:
Marcadores de condição:
| Marcador | Significado | Exemplo |
|---|---|---|
| eq | Igual (correspondência exata) | Preço = $50 |
| neq | Não igual | Status ≠ "esgotado" |
| in | Contém (um dos) | Cor em ["vermelho", "azul"] |
| nin | Não contém | Categoria não em ["arquivada"] |
| mth | Maior que | Preço > $100 |
| lth | Menor que | Preço < $50 |
| exs | Existe (tem valor) | Tem desconto |
| nexs | Não existe (vazio) | Sem desconto |
Status e Links de Produtos
Status dos Produtos criam condições de filtragem adicionais além dos filtros de atributos existentes para uma organização de produtos mais sofisticada.
Links de Produtos permitem estabelecer conexões entre produtos com base em critérios de atributos. Por exemplo, você pode vincular todos os produtos com o mesmo atributo de cor (ex.: todos os telefones pretos juntos).
📊 Tabela de Referência Rápida - Métodos Comuns
| Método | Descrição | Caso de Uso |
|---|---|---|
| getProducts() | Obter todos os produtos com filtragem/ordenamento | Página principal do catálogo |
| getProductById() | Obter produto único por ID | Página de detalhes do produto |
| getProductsByPageId() | Obter produtos da categoria por ID | Página da categoria |
| getProductsByPageUrl() | Obter produtos da categoria por URL | Página da categoria por URL |
| getRelatedProductsById() | Obter produtos relacionados/similares | Seção "Você também pode gostar" |
| searchProduct() | Buscar produtos por consulta | Funcionalidade de busca |
| getProductsCount() | Obter contagem total de produtos | Informações de paginação |
| getProductsCountByPageId() | Obter contagem de produtos por ID de categoria | Paginação da categoria |
| getProductsCountByPageUrl() | Obter contagem de produtos por URL de categoria | Paginação da categoria |
| getProductBlockById() | Obter bloco de produto por ID | Blocos de conteúdo do produto |
| getProductsEmptyPage() | Obter estrutura de página de produtos vazia | Tratamento de estado vazio |
| getProductsPriceByPageUrl() | Obter preços de produtos por URL de categoria | Filtragem de preços |
❓ Perguntas Comuns (FAQ)
Posso filtrar por múltiplos critérios ao mesmo tempo?
Sim! Combine múltiplos filtros em um array.
Como eu lido com variantes de produtos (tamanhos, cores)?
As variantes de produtos são armazenadas em attributeValues.
Como eu implemento o botão "Carregar Mais"?
Use offset para carregar mais produtos.
Posso mostrar produtos de múltiplas categorias?
Sim, use o marcador de condição category in.
Como eu implemento a seção "Novidades"?
Ordene por data de criação ou use a categoria pai para ordenação manual.
💡 Notas Importantes
Configuração das Categorias do Catálogo
Importante: Antes de adicionar produtos, você deve criar categorias do catálogo através do módulo Páginas. As categorias do catálogo são páginas do tipo Catálogo.
Fluxo de Trabalho:
- Vá para o módulo Páginas no painel de administração
- Crie páginas com o tipo "Catálogo"
- Essas páginas se tornam suas categorias de produtos
- Adicione produtos a essas categorias via Catálogo > Produtos
Recursos do Catálogo
O módulo Catálogo fornece ferramentas abrangentes:
- Aba Produtos - Espaço principal para criar/gerenciar itens do catálogo
- Filtros de Produtos - Permitem busca rápida usando critérios especificados
- Links de Produtos - Conectam produtos relacionados com base em atributos
- Status dos Produtos - Crie condições de filtragem personalizadas
- Upload do Catálogo - Importação em massa de produtos
- Configurações - Configure o comportamento do catálogo
Além do E-commerce
O Catálogo não se limita a produtos - pode ser usado para:
- Galerias Multimídia - Fotos, vídeos, coleções de arte
- Itens de Portfólio - Trabalhos de design, estudos de caso
- Bibliotecas de Documentos - Recursos, downloads
- Catálogos de Eventos - Conferências, webinars
- Coleções de Receitas - Comidas, bebidas, culinária
Otimização de Desempenho
Cache produtos acessados com frequência para reduzir chamadas de API e melhorar os tempos de carregamento.
Sempre Filtrar Produtos Ativos
Em produção, sempre mostre apenas produtos ativos filtrando com statusId: 1.
Lidar com Imagens Ausentes
Forneça imagens de fallback para produtos sem imagens para manter uma UI consistente.
🎓 Melhores Práticas
- Sempre use paginação (limite + offset)
- Filtre por
statusId: 1em produção - Cache listas de produtos para reduzir chamadas de API
- Lide com "fora de estoque" de forma elegante
- Forneça imagens de fallback
- Use marcadores para produtos em destaque (não IDs)
- Implemente busca com debounce
- Adicione estados de carregamento na UI
Mais informações sobre o Catálogo no painel de administração do OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/catalog
Definição do módulo Products
const { Products } = defineOneEntry( "sua-url-do-projeto", { "token": "seu-token-de-aplicativo" });
Este módulo aceita um conjunto de parâmetros de usuário chamado userQuery. Se os parâmetros não forem passados para o método, o valor padrão será aplicado. Alguns métodos aceitam o corpo como um parâmetro para filtragem. Se você não quiser configurar a ordenação, passe um array vazio ou não passe nada.
Parâmetros:
const userQuery = { offset: 0, limit: 30, sortOrder: 'DESC', sortKey: 'id',}
Esquema
offset: número
Parâmetro de paginação. Padrão 0
exemplo: 0
limit: número
parâmetro de paginação. Padrão 30
exemplo: 30
sortKey: string
Campo para ordenação (padrão não definido - ordenação por posição, valores possíveis: id, título, data, preço, posição)
Valores disponíveis: id, posição, título, data, preço
sortOrder: string
ordem de ordenação DESC | ASC (padrão DESC)
exemplo: "DESC"
Por padrão, você pode recuperar 10 objetos. Isso se deve ao limite de registro nas configurações de permissões do módulo.
Para que a paginação funcione corretamente, você precisa configurar Permissões do Módulo de acordo com suas necessidades na seção correspondente.
"conditionMarker" pelo qual os valores são filtrados (não definido por padrão), valores possíveis:
'in' - Contém,
'nin' - Não contém,
'eq' - Igual,
'neq' - Não igual,
'mth' - Maior que,
'lth' - Menor que,
'exs' - Existe,
'nexs' - Não existe
Use condições para encontrar dados específicos de produtos:
attributeMarker: O identificador de texto do atributo indexado pelo qual os valores são filtrados. conditionMarker: O tipo de condição a ser aplicada ao valor do atributo.
| Marcador | Significado | Exemplo |
|---|---|---|
| eq | Igual | statusId = 1 (apenas ativos) |
| neq | Não igual | categoria ≠ "arquivada" |
| in | Contém (um dos) | categoria em ["eletrônicos", "livros"] |
| nin | Não contém | marca não em ["marca_falsa"] |
| exs | Existe (tem valor) | Tem descrição |
| nexs | Não existe | Sem imagem |
conditionValue: O valor a ser comparado.
🔗 Documentação Relacionada
- Painel de Administração do OneEntry - Catálogo - Documentação oficial do painel de administração
- Módulo Páginas - Crie categorias de catálogo (páginas do tipo Catálogo)
- Módulo AttributesSets - Campos e atributos personalizados de produtos
- Módulo Templates - Modelos de exibição de produtos
- Módulo Blocks - Blocos de conteúdo de produto reutilizáveis
- Módulo Orders - Gerencie pedidos de produtos