Skip to content

Documentação de Vitrines

Visão Geral

A vitrine é responsável por exibir produtos de forma estratégica dentro da loja 🛍️.

Ela permite destacar itens com base em regras específicas de filtragem, possibilitando criar seções como produtos mais vendidos, lançamentos, ofertas ou seleções personalizadas.

A configuração da vitrine é baseada em filtros armazenados no sistema, que determinam quais produtos devem ser retornados e exibidos. Esses filtros podem combinar diferentes critérios, como atributos do produto, categorias, ordenação e outras condições.

Internamente, o sistema utiliza a estrutura de listagem de produtos, aplicando os filtros configurados para montar automaticamente o conjunto de produtos exibidos na vitrine.

Essa abordagem permite criar desde vitrines simples até vitrines altamente segmentadas, adaptando a exibição de produtos conforme campanhas, estratégias comerciais ou necessidades específicas da loja.

Entidades Relacionadas

Produtos

Os produtos são a principal entidade relacionada às vitrines.

Cada vitrine retorna um conjunto de produtos que atendem aos critérios de filtragem configurados, permitindo organizar e destacar itens de maneira estratégica dentro da loja.

Essa relação é dinâmica, pois os produtos exibidos podem variar automaticamente conforme os filtros aplicados, mantendo a vitrine sempre atualizada.

Localização

A vitrine pode estar vinculada a uma localização específica.

As localizações são gerenciadas pelo frontend e permitem retornar um conjunto de entidades (incluindo vitrines) com base no local informado, determinando onde a vitrine deve ser exibida dentro da interface da loja.

Para mais informações sobre localizações, clique [aqui]({{ MAIN_URL }}/).

Listar Vitrines por Código

GET /api/v3/publics/template/showcases

Obtém vitrines de produtos por códigos

Descrição

Endpoint responsável por retornar vitrines de produtos pré-configuradas por código, incluindo produtos filtrados, ordenados e paginados conforme regras definidas.

Suporta vitrines de produtos mais vendidos e integração com grupos de banners.

---

Produtos Mais Vendidos

Vitrines configuradas com best_sellers: true retornam produtos ordenados por quantidade vendida.

Regras aplicadas:

  • Considera apenas pedidos com status: PAID, INVOICED, SENT, DELIVERED
  • Limita o resultado aos 1000 produtos mais vendidos
  • Ordena por quantidade total vendida (do maior para o menor)
  • ---

    Integração com Banners

    O campo bannerGroups contém os códigos dos grupos de banners que podem ser exibidos junto à vitrine, permitindo composições estratégicas de conteúdo promocional.

    ---

    Observações

  • Vitrines Dinâmicas: Os produtos são buscados em tempo real com base nas regras configuradas
  • Trade Policy: Os produtos respeitam a política comercial do canal
  • Cache: Recomenda-se utilização de cache no frontend, especialmente para vitrines de homepage
  • Performance: Utilize o parâmetro fields para carregar apenas os dados necessários
  • Estoque: Produtos sem estoque podem ser filtrados conforme as regras configuradas
  • Agendamento: A vitrine pode possuir agendamento de exibição configurado no painel administrativo

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Campos Disponíveis (fields)

Especifique apenas os campos necessários para otimizar a performance:

CampoDescrição
brandInformações completas da marca do produto
flagsFlags do produto (showInSite, saleWithoutStock, minimumStock)
mainUrlURL principal do produto
secondaryUrlsURLs secundárias do produto
descriptionDescrições (short, full, searchDescription)
parentProductProduto pai do produto atual
indicatedProductsProdutos indicados relacionados
relatedProductsProdutos relacionados
taxInformações de impostos e taxas
filtersFiltros e atributos aplicáveis
stockByStorageEstoque por armazém
stockInformações consolidadas de estoque
sealsSelos e certificações do produto
mainCategoryCategoria principal
categoriesTodas as categorias do produto
categoryBreadcrumbBreadcrumb de navegação de categorias
dimensionDimensões físicas (peso, altura, largura, comprimento)
variationVariações do produto (cores, tamanhos, etc)
mediaMídias (imagens, vídeos, arquivos)
pricePreço, promoções e parcelamento
priceRulesRegras de preço aplicadas
bannerGroupsGrupos de banners associados
reviewAvaliações e reviews
statusStatus do produto
haveChildrenVerifica se tem produtos filhos
restrictionRestrição de compra do produto (tradePolicyId, requiredAge)
availableCouponsRetorna até 10 cupons aplicáveis ao produto

Estrutura do field availableCoupons

Cada item do array representa um cupom aplicável ao produto. O nó discounts detalha as faixas de desconto:

1{
2 "id": 15,
3 "hash": "PROMO10",
4 "discounts": [
5 {
6 "entityId": 15,
7 "entity": "coupon",
8 "itemAmount": 3,
9 "value": 10
10 }
11 ],
12 "createdAt": "2026-01-01 00:00:00",
13 "updatedAt": "2026-01-01 00:00:00"
14}

CampoTipoDescrição
idintegerID do cupom
hashstringCódigo do cupom (inserido pelo cliente no checkout)
discounts[].entityIdintegerID da entidade referenciada em entity
discounts[].entitystringEntidade que recebe o desconto
discounts[].itemAmountnumberQuantidade mínima de itens para que o desconto em value seja aplicado
discounts[].valuenumberValor do desconto aplicado quando itemAmount é atingido

Parâmetros de Corpo

ParâmetroTipoObrigatórioDescrição
codesarraySimArray com códigos das vitrines desejadas
codes.*stringSimCódigo individual de vitrine
fieldsarrayNãoCampos específicos do produto a retornar
fields.*stringNãoNome do campo (ex: "price", "brand", "stock")

Exemplo de Requisição

1curl --request GET \
2 --url '{{MAIN_URL}}/publics/template/showcases' \
3 --header 'uappi-cookie-name: uappi-cookie' \
4 --data '{
5 "codes": ["vitrine-lancamentos", "vitrine-mais-vendidos"],
6 "fields": ["price", "brand", "mainCategory", "media"]
7 }'

✅ Resposta de Sucesso

1{
2 "status": true,
3 "data": [
4 {
5 "id": 1,
6 "code": "vitrine-lancamentos",
7 "name": "Lançamentos",
8 "title": "Últimos Lançamentos",
9 "description": "Produtos recém-chegados à loja",
10 "bannerGroups": ["banner-lancamentos"],
11 "products": [
12 {
13 "id": 44,
14 "type": "product",
15 "sku": "ABC123",
16 "name": "TechBrand Smartphone",
17 "priority": 1,
18 "basePrice": 1199,
19 "active": true,
20 "review": null,
21 "isGiftCard": false,
22 "stock": null,
23 "stocks": null,
24 "originalPrice": null,
25 "price": null,
26 "priceRules": null,
27 "brand": null,
28 "flags": null,
29 "tax": null,
30 "indicatedProducts": null,
31 "relatedProducts": null,
32 "filters": null,
33 "seals": null,
34 "mainCategory": null,
35 "categories": null,
36 "categoryBreadcrumb": null,
37 "dimensions": null,
38 "parentProductId": null,
39 "combination": [],
40 "currentAttributes": null,
41 "variations": null,
42 "medias": null,
43 "bannerGroups": [],
44 "status": null,
45 "createdAt": "2022-10-03 17:28:09",
46 "updatedAt": "2025-09-23 01:31:32",
47 "url": "",
48 "urls": [],
49 "linkedTradePolicies": null,
50 "description": null
51 },
52 "pagination": {
53 "limit": 12,
54 "offset": 0,
55 "pages": 1,
56 "registers": 8
57 }
58 ]
59 }
60 ]
61}

Possíveis Erros

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2 "status": false,
3 "data": {
4 "code": 404,
5 "errorCode": "UAPPI_STORE_SHOWCASE_NOT_FOUND",
6 "message": "Showcase not found with the provided codes."
7 }
8}

Listar Vitrines por Produto

GET /api/v3/publics/template/showcases/{productId}

Obtém vitrines relacionadas a um produto específico

Descrição

Endpoint responsável por retornar vitrines de produtos geradas automaticamente com base em um produto específico.

Permite obter:

  • Produtos da mesma categoria principal
  • Produtos indicados (upsell / cross-sell)
  • Produtos relacionados
  • ---

    Lógica de Cada Tipo de Vitrine

    1. Categoria Principal (mainCategory)

  • Busca produtos da mesma categoria principal do produto base
  • Exclui o próprio produto da listagem
  • Indicado para seções como: "Outros produtos desta categoria"
  • ---

    2. Produtos Indicados (indicated)

  • Retorna produtos cadastrados como "indicados" no produto base
  • Configuração no admin: Produto → Produtos Indicados
  • Ideal para estratégias de upsell e cross-sell
  • ---

  • Retorna produtos cadastrados como "relacionados" no produto base
  • Configuração no admin: Produto → Produtos Relacionados
  • Indicado para seções como: "Compre Junto" ou "Produtos Similares"
  • ---

    Observações

  • Limite Fixo: Cada vitrine retorna no máximo 15 produtos
  • Sanitização: Tipos inválidos informados na requisição são automaticamente ignorados
  • Duplicatas: Tipos duplicados são removidos automaticamente
  • Vazio: Caso não existam produtos para determinado tipo, o campo registers retorna um array vazio
  • Trade Policy: Os produtos respeitam a política comercial configurada
  • Fields: Utilize o parâmetro fields para otimizar o payload (mesma lógica das outras vitrines)

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
productIdintegerSimID único de produto

Campos Disponíveis (fields)

Especifique apenas os campos necessários para otimizar a performance:

CampoDescrição
brandInformações completas da marca do produto
flagsFlags do produto (showInSite, saleWithoutStock, minimumStock)
mainUrlURL principal do produto
secondaryUrlsURLs secundárias do produto
descriptionDescrições (short, full, searchDescription)
parentProductProduto pai do produto atual
indicatedProductsProdutos indicados relacionados
relatedProductsProdutos relacionados
taxInformações de impostos e taxas
filtersFiltros e atributos aplicáveis
stockByStorageEstoque por armazém
stockInformações consolidadas de estoque
sealsSelos e certificações do produto
mainCategoryCategoria principal
categoriesTodas as categorias do produto
categoryBreadcrumbBreadcrumb de navegação de categorias
dimensionDimensões físicas (peso, altura, largura, comprimento)
variationVariações do produto (cores, tamanhos, etc)
mediaMídias (imagens, vídeos, arquivos)
pricePreço, promoções e parcelamento
priceRulesRegras de preço aplicadas
bannerGroupsGrupos de banners associados
reviewAvaliações e reviews
statusStatus do produto
haveChildrenVerifica se tem produtos filhos
restrictionRestrição de compra do produto (tradePolicyId, requiredAge)
availableCouponsRetorna até 10 cupons aplicáveis ao produto

Estrutura do field availableCoupons

Cada item do array representa um cupom aplicável ao produto. O nó discounts detalha as faixas de desconto:

1{
2 "id": 15,
3 "hash": "PROMO10",
4 "discounts": [
5 {
6 "entityId": 15,
7 "entity": "coupon",
8 "itemAmount": 3,
9 "value": 10
10 }
11 ],
12 "createdAt": "2026-01-01 00:00:00",
13 "updatedAt": "2026-01-01 00:00:00"
14}

CampoTipoDescrição
idintegerID do cupom
hashstringCódigo do cupom (inserido pelo cliente no checkout)
discounts[].entityIdintegerID da entidade referenciada em entity
discounts[].entitystringEntidade que recebe o desconto
discounts[].itemAmountnumberQuantidade mínima de itens para que o desconto em value seja aplicado
discounts[].valuenumberValor do desconto aplicado quando itemAmount é atingido

Parâmetros de Corpo

ParâmetroTipoObrigatórioDescrição
productIdintegerSimID do produto base
showcasesarraySimTipos de vitrines a retornar
showcases.*stringSimTipo: mainCategory, indicated, related
fieldsarrayNãoCampos específicos do produto a retornar
fields.*stringNãoNome do campo

Tipos de Vitrine Disponíveis

TipoValorDescrição
Categoria PrincipalmainCategoryProdutos da mesma categoria principal
IndicadosindicatedProdutos indicados/sugeridos (upsell)
RelacionadosrelatedProdutos relacionados/similares

Exemplo de Requisição

1curl --request GET \
2 --url '{{MAIN_URL}}/publics/template/showcases/1001' \
3 --header 'uappi-cookie-name: uappi-cookie' \
4 --data '{
5 "showcases": ["mainCategory", "indicated", "related"],
6 "fields": ["price", "brand", "media", "mainUrl"]
7 }'

✅ Resposta de Sucesso

1{
2 "status": true,
3 "data": {
4 "mainCategory": [
5 {
6 "id": 123,
7 "type": "product",
8 "sku": "ABC123",
9 "name": "Smartphone TechBrand 123",
10 "priority": 1,
11 "basePrice": 1199,
12 "active": true,
13 "review": null,
14 "isGiftCard": false,
15 "stock": null,
16 "stocks": null,
17 "originalPrice": null,
18 "price": null,
19 "priceRules": null,
20 "brand": null,
21 "flags": null,
22 "tax": null,
23 "indicatedProducts": null,
24 "relatedProducts": null,
25 "filters": null,
26 "seals": null,
27 "mainCategory": null,
28 "categories": null,
29 "categoryBreadcrumb": null,
30 "dimensions": null,
31 "parentProductId": null,
32 "combination": [],
33 "currentAttributes": null,
34 "variations": null,
35 "medias": null,
36 "bannerGroups": [],
37 "status": null,
38 "createdAt": "2022-12-13 14:44:12",
39 "updatedAt": "2025-09-17 14:11:42",
40 "url": "",
41 "urls": [],
42 "linkedTradePolicies": null,
43 "description": null
44 }
45 ],
46 "indicated": [
47 {
48 "id": 1235,
49 "type": "product",
50 "sku": "ABC321",
51 "name": "Smartphone TechBrand 321",
52 "priority": 2,
53 "basePrice": 1199,
54 "active": true,
55 "review": null,
56 "isGiftCard": false,
57 "stock": null,
58 "stocks": null,
59 "originalPrice": null,
60 "price": null,
61 "priceRules": null,
62 "brand": null,
63 "flags": null,
64 "tax": null,
65 "indicatedProducts": null,
66 "relatedProducts": null,
67 "filters": null,
68 "seals": null,
69 "mainCategory": null,
70 "categories": null,
71 "categoryBreadcrumb": null,
72 "dimensions": null,
73 "parentProductId": null,
74 "combination": [],
75 "currentAttributes": null,
76 "variations": null,
77 "medias": null,
78 "bannerGroups": [],
79 "status": null,
80 "createdAt": "2022-12-13 14:44:12",
81 "updatedAt": "2025-09-17 14:11:42",
82 "url": "",
83 "urls": [],
84 "linkedTradePolicies": null,
85 "description": null
86 }
87 ],
88 "related": [
89 {
90 "id": 1236,
91 "type": "product",
92 "sku": "ABC456",
93 "name": "Smartphone TechBrand 456",
94 "priority": 3,
95 "basePrice": 1199,
96 "active": true,
97 "review": null,
98 "isGiftCard": false,
99 "stock": null,
100 "stocks": null,
101 "originalPrice": null,
102 "price": null,
103 "priceRules": null,
104 "brand": null,
105 "flags": null,
106 "tax": null,
107 "indicatedProducts": null,
108 "relatedProducts": null,
109 "filters": null,
110 "seals": null,
111 "mainCategory": null,
112 "categories": null,
113 "categoryBreadcrumb": null,
114 "dimensions": null,
115 "parentProductId": null,
116 "combination": [],
117 "currentAttributes": null,
118 "variations": null,
119 "medias": null,
120 "bannerGroups": [],
121 "status": null,
122 "createdAt": "2022-12-13 14:44:12",
123 "updatedAt": "2025-09-17 14:11:42",
124 "url": "",
125 "urls": [],
126 "linkedTradePolicies": null,
127 "description": null
128 }
129 ]
130 }
131}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2 "status": false,
3 "data": {
4 "code": 404,
5 "errorCode": "UAPPI_STORE_PRODUCT_NOT_FOUND",
6 "message": "Product not found."
7 }
8}

Uappi é a melhor opção para o crescimento da sua loja!

;