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:

❌ Sem o Módulo de Produtos (codificado):
- Adicionar novo produto → Mudar código → Deploy
- Mudar preço → Mudança de código → Deploy
- 1000 produtos = arquivo de código massivo

✅ Com o Módulo de Produtos (dinâmico):
- Adicionar novo produto → Atualizar no admin → Ao vivo instantaneamente
- Mudar preço → Atualizar no admin → Ao vivo instantaneamente
- 10.000 produtos = chamadas de API simples

✨ 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 filtragem especificados
Atributos personalizados - Marca, Tamanho, Cor, Material, etc.

Exemplo de hierarquia:

📁 Eletrônicos
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Roupas
  ├─ 👕 Camisetas
  └─ 👖 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 de trabalho 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
getProductsByPageId()	Produtos de categoria específica (por ID)	Página de categoria
getProductsByPageUrl()	Produtos de categoria específica (por URL)	Página de 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, 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 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 de categoria por ID	Página de categoria
getProductsByPageUrl()	Obter produtos de categoria por URL	Página de 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 de categoria
getProductsCountByPageUrl()	Obter contagem de produtos por URL de categoria	Paginação de 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 de 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 de trabalho 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 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: 1 em 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 chamados 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"

"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

🔗 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

Introdução

🎯 O que este módulo faz?​

📖 Explicação Simples​

✨ Conceitos Chave​

O que é um Produto?​

Estrutura do Produto​

Organização do Produto​

📋 O que você precisa saber​

Arquitetura do Catálogo​

Formas de Obter Produtos​

Paginação Explicada Simplesmente​

Opções de Ordenação​

Filtrando Produtos​

Status e Links de Produtos​

📊 Tabela de Referência Rápida - Métodos Comuns​

❓ Perguntas Comuns (FAQ)​

Posso filtrar por múltiplos critérios ao mesmo tempo?​

Como eu lido com variantes de produtos (tamanhos, cores)?​

Como eu implemento o botão "Carregar Mais"?​

Posso mostrar produtos de múltiplas categorias?​

Como eu implemento a seção "Novidades"?​

💡 Notas Importantes​

Configuração das Categorias do Catálogo​

Recursos do Catálogo​

Além do E-commerce​

Otimização de Desempenho​

Sempre Filtrar Produtos Ativos​

Lidar com Imagens Ausentes​

🎓 Melhores Práticas​

Definição do módulo Products​

🔗 Documentação Relacionada​