Introdução

Name: OneEntry SDK
Author: OneEntry

Gerencie produtos de e-commerce com catálogos dinâmicos, filtragem e busca.

Mais informações sobre o Catálogo no painel administrativo do OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 O que este módulo faz?

O módulo Products (Catálogo) permite que você recupere, filtre, busque e classifique produtos em sua loja online ou coleções multimídia. Você gerencia o catálogo no painel administrativo do OneEntry (Catálogo > Produtos); seu aplicativo busca produtos dinamicamente, então mudar um preço ou atributo no admin entra em vigor sem necessidade de reimplantação.

Além do e-commerce, o Catálogo também se adapta a galerias multimídia, portfólios, bibliotecas de documentos e outras coleções de conteúdo.

🚀 Início Rápido

Inicialize o módulo a partir de defineOneEntry:


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

Busque uma página de produtos e leia seus campos:

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

A maioria dos métodos de listagem compartilha a mesma estrutura: um filtro body opcional, um langCode e um userQuery opcional (paginação/classificação). Veja Parâmetros abaixo para o conjunto completo.

✨ Conceitos Chave

O que é um Produto?

Um produto é uma entidade de catálogo (IProductsEntity) composta por:

Informações básicas - localizeInfos (título, etc.), sku, preço
Imagens - fotos do produto / galeria (armazenadas como atributos)
Atributos personalizados - quaisquer campos que você definir (attributeValues): marca, material, tamanho, cor, variantes, estoque, …
Localização - conteúdo por idioma

Não existem tipos de produtos fixos no SDK — qualquer estrutura (variantes, opções, downloads, pacotes) é modelada com os atributos personalizados que você configura para o catálogo.

Organização de Produtos

Os produtos são organizados através de várias funcionalidades do catálogo:

Categorias - seções do catálogo (páginas do tipo Catálogo, criadas no módulo Páginas)
Status dos Produtos - condições de filtragem adicionais além dos filtros de atributos (por exemplo, "em estoque", "promoção")
Links de Produtos - conectam produtos por critérios de atributo (por exemplo, todos os telefones pretos juntos)
Filtros de Produtos - busca rápida por critérios de filtro especificados
Atributos personalizados - marca, tamanho, cor, material, …

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

As categorias do catálogo são páginas do tipo Catálogo criadas através do módulo Páginas — crie-as antes de adicionar produtos:

Abra o módulo Páginas no painel administrativo.
Crie páginas com o tipo Catálogo — estas se tornam suas categorias de produtos.
Adicione produtos a essas categorias via Catálogo > Produtos.

O Catálogo administrativo também fornece Upload em massa do Catálogo, Filtros de Produtos, Links de Produtos, Status dos Produtos e Configurações por catálogo.

Paginação

Não carregue tudo de uma vez — pagine pelos resultados com limit e offset:

Fórmula de Offset: offset = (pageNumber - 1) * limit

Limite padrão: você pode recuperar 10 objetos por padrão. Para paginar mais, configure Permissões do Módulo conforme suas necessidades.

Classificação

Passe sortKey e sortOrder em userQuery:

sortKey	O que faz	Exemplo de Uso
preço	Classificar por preço	Mostrar os mais baratos primeiro
data	Classificar por data de criação	Mostrar os produtos mais novos
título	Classificar alfabeticamente	Lista de produtos A-Z
posição	Ordem personalizada (padrão)	Ordem escolhida manualmente no admin
id	Classificar por ID	Classificação técnica

Ordem de classificação: ASC (baixo→alto) ou DESC (alto→baixo, padrão).

Filtragem

A filtragem é feita através do body da requisição (um array de IFilterParams), não userQuery. Cada condição combina um attributeMarker, um conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs) e um conditionValue. Combine várias condições no array para filtrar por múltiplos critérios ao mesmo tempo. A referência completa das condições está em Parâmetros abaixo.

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

Método	Descrição	Caso de Uso
getProducts()	Obter todos os produtos com filtragem/classificação	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 da página	Página de categoria
getProductsByPageUrl()	Obter produtos da categoria por URL da página	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 da categoria	Paginação de categoria
getProductsCountByPageUrl()	Obter contagem de produtos por URL da 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 da página	Filtragem de preços
getProductsByIds()	Obter produtos por uma lista de IDs	Carrinho, lista de desejos, comparação
getProductsByVectorSearch()	Busca semântica (vetorial) por produtos	Busca com inteligência artificial

Parâmetros

Este módulo aceita um conjunto de parâmetros de usuário chamado userQuery. Se um parâmetro não for passado, seu padrão é aplicado. Alguns métodos também aceitam um body para filtragem — passe um array vazio (ou nada) quando não precisar de filtros.


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
    signPrice: 'orders',
}

Nota: a estrutura de userQuery depende do método. Os campos acima são a base comum (IProductsQueryBase), usada por getProducts, getProductsByPageId, getProductsByPageUrl e getProductsEmptyPage. Outros métodos diferem: getRelatedProductsById também aceita statusMarker e templateMarker; getProductsPriceByPageUrl também aceita statusMarker (sem sortKey); getProductsByIds aceita apenas signPrice. A filtragem (attributeMarker / conditionMarker / conditionValue) é feita através do body da requisição, não userQuery — veja abaixo.

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 classificação (padrão não definido - classificaçã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 classificação DESC | ASC (padrão DESC)
exemplo: "DESC"

signPrice: string
Marcador de armazenamento de ordem para fixação de preço. Se o parâmetro estiver definido, o preço é fixado por um certo tempo (veja a seção Fixação do preço abaixo).
exemplo: "orders"

Campos específicos do método: statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) e templateMarker (getRelatedProductsById) — string | null, padrão null.

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 ativo)
neq	Não igual	categoria ≠ "arquivada"
in	Contém (um dos)	categoria in ["eletrônicos", "livros"]
nin	Não contém	marca not in ["marca_falsa"]
mth	Maior que	preço > 100
lth	Menor que	estoque < 10
exs	Existe (tem valor)	Tem descrição
nexs	Não existe	Sem imagem

conditionValue: O valor a ser comparado.

Fixação do preço (signPrice)

Quando você busca produtos, pode passar um parâmetro opcional signPrice dentro de userQuery (também é um argumento nos métodos de recomendação do módulo Blocks). Ele aceita o marcador de um armazenamento de ordem e pede ao servidor para travar o preço retornado por um tempo limitado.

signPrice — tipo string

Marcador de armazenamento de ordem para fixação de preço. Se o parâmetro estiver definido, o preço é fixado por um certo tempo.

Por que usá-lo. Os preços podem mudar enquanto um cliente está comprando — um desconto começa, ou um admin edita o preço. signPrice garante que o preço mostrado no catálogo ou carrinho é exatamente o preço cobrado no checkout, para que não haja variação entre a navegação e o pedido.

Como funciona:

Busque produtos com signPrice definido para seu marcador de armazenamento de ordem (por exemplo, "orders").
Cada produto retornado agora carrega um campo signedPrice — um token assinado que codifica o preço travado.
Envie esse token signedPrice de volta quando você criar o pedido, para que o servidor honre o preço fixado.


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "orders"
});

const signedPrice = items[0].signedPrice;

➡️ O token retornado é consumido por createOrder(). Veja onde pegá-lo e como passá-lo na seção Preço fixo do produto (signedPrice) do módulo Orders.

❓ Perguntas Comuns (FAQ)

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

Sim — passe várias condições no array do body; elas são combinadas:

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

Como faço para lidar com variantes de produtos (tamanhos, cores)?

As variantes são armazenadas nos attributeValues do produto — leia-as do objeto de produto buscado. A estrutura é qualquer conjunto de atributos que você configurou para o catálogo.

Como implemento um botão "Carregar Mais"?

Aumente offset em limit a cada clique e anexe os novos items à sua lista (use total para saber quando parar).

Posso mostrar produtos de múltiplas categorias?

Sim — filtre com o atributo category e o marcador de condição in, passando a lista de valores de categoria.

Como implemento uma seção "Novidades"?

Classifique por data de criação: userQuery: { sortKey: "date", sortOrder: "DESC" }.

🎓 Melhores Práticas

Sempre pagine (limit + offset) — nunca busque todo o catálogo de uma vez.
Cache listas de produtos para categorias frequentemente acessadas para reduzir chamadas à API.
Use signPrice quando os preços entram em um carrinho/checkout para que o preço não possa variar.
Lide com resultados vazios (total === 0) e campos ausentes (preço, imagens) de forma elegante.

🔗 Documentação Relacionada

Painel Administrativo OneEntry - Catálogo - Documentação oficial do painel administrativo
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

🎯 O que este módulo faz?​

🚀 Início Rápido​

✨ Conceitos Chave​

O que é um Produto?​

Organização de Produtos​

📋 O que você precisa saber​

Arquitetura do Catálogo​

Paginação​

Classificação​

Filtragem​

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

Parâmetros​

Fixação do preço (signPrice)​

❓ Perguntas Comuns (FAQ)​

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

Como faço para lidar com variantes de produtos (tamanhos, cores)?​

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

Posso mostrar produtos de múltiplas categorias?​

Como implemento uma seção "Novidades"?​

🎓 Melhores Práticas​

🔗 Documentação Relacionada​