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
/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)
- 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
fieldspara 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
---
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
Parâmetros de Query
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Content-Type | application/json | Tipo de conteúdo |
Campos Disponíveis (fields)
Especifique apenas os campos necessários para otimizar a performance:
| Campo | Descrição |
|---|---|
| brand | Informações completas da marca do produto |
| flags | Flags do produto (showInSite, saleWithoutStock, minimumStock) |
| mainUrl | URL principal do produto |
| secondaryUrls | URLs secundárias do produto |
| description | Descrições (short, full, searchDescription) |
| parentProduct | Produto pai do produto atual |
| indicatedProducts | Produtos indicados relacionados |
| relatedProducts | Produtos relacionados |
| tax | Informações de impostos e taxas |
| filters | Filtros e atributos aplicáveis |
| stockByStorage | Estoque por armazém |
| stock | Informações consolidadas de estoque |
| seals | Selos e certificações do produto |
| mainCategory | Categoria principal |
| categories | Todas as categorias do produto |
| categoryBreadcrumb | Breadcrumb de navegação de categorias |
| dimension | Dimensões físicas (peso, altura, largura, comprimento) |
| variation | Variações do produto (cores, tamanhos, etc) |
| media | Mídias (imagens, vídeos, arquivos) |
| price | Preço, promoções e parcelamento |
| priceRules | Regras de preço aplicadas |
| bannerGroups | Grupos de banners associados |
| review | Avaliações e reviews |
| status | Status do produto |
| haveChildren | Verifica se tem produtos filhos |
| restriction | Restrição de compra do produto (tradePolicyId, requiredAge) |
| availableCoupons | Retorna 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": 1010 }11 ],12 "createdAt": "2026-01-01 00:00:00",13 "updatedAt": "2026-01-01 00:00:00"14}| Campo | Tipo | Descrição |
|---|---|---|
id | integer | ID do cupom |
hash | string | Código do cupom (inserido pelo cliente no checkout) |
discounts[].entityId | integer | ID da entidade referenciada em entity |
discounts[].entity | string | Entidade que recebe o desconto |
discounts[].itemAmount | number | Quantidade mínima de itens para que o desconto em value seja aplicado |
discounts[].value | number | Valor do desconto aplicado quando itemAmount é atingido |
Parâmetros de Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
codes | array | Sim | Array com códigos das vitrines desejadas |
codes.* | string | Sim | Código individual de vitrine |
fields | array | Não | Campos específicos do produto a retornar |
fields.* | string | Não | Nome 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": null51 },52 "pagination": {53 "limit": 12,54 "offset": 0,55 "pages": 1,56 "registers": 857 }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
/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
- 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"
- 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"
- 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
registersretorna um array vazio - Trade Policy: Os produtos respeitam a política comercial configurada
- Fields: Utilize o parâmetro
fieldspara otimizar o payload (mesma lógica das outras vitrines)
---
Lógica de Cada Tipo de Vitrine
1. Categoria Principal (mainCategory)
---
2. Produtos Indicados (indicated)
---
3. Produtos Relacionados (related)
---
Observações
Parâmetros de Query
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Content-Type | application/json | Tipo de conteúdo |
Parâmetros da URL
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| productId | integer | Sim | ID único de produto |
Campos Disponíveis (fields)
Especifique apenas os campos necessários para otimizar a performance:
| Campo | Descrição |
|---|---|
| brand | Informações completas da marca do produto |
| flags | Flags do produto (showInSite, saleWithoutStock, minimumStock) |
| mainUrl | URL principal do produto |
| secondaryUrls | URLs secundárias do produto |
| description | Descrições (short, full, searchDescription) |
| parentProduct | Produto pai do produto atual |
| indicatedProducts | Produtos indicados relacionados |
| relatedProducts | Produtos relacionados |
| tax | Informações de impostos e taxas |
| filters | Filtros e atributos aplicáveis |
| stockByStorage | Estoque por armazém |
| stock | Informações consolidadas de estoque |
| seals | Selos e certificações do produto |
| mainCategory | Categoria principal |
| categories | Todas as categorias do produto |
| categoryBreadcrumb | Breadcrumb de navegação de categorias |
| dimension | Dimensões físicas (peso, altura, largura, comprimento) |
| variation | Variações do produto (cores, tamanhos, etc) |
| media | Mídias (imagens, vídeos, arquivos) |
| price | Preço, promoções e parcelamento |
| priceRules | Regras de preço aplicadas |
| bannerGroups | Grupos de banners associados |
| review | Avaliações e reviews |
| status | Status do produto |
| haveChildren | Verifica se tem produtos filhos |
| restriction | Restrição de compra do produto (tradePolicyId, requiredAge) |
| availableCoupons | Retorna 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": 1010 }11 ],12 "createdAt": "2026-01-01 00:00:00",13 "updatedAt": "2026-01-01 00:00:00"14}| Campo | Tipo | Descrição |
|---|---|---|
id | integer | ID do cupom |
hash | string | Código do cupom (inserido pelo cliente no checkout) |
discounts[].entityId | integer | ID da entidade referenciada em entity |
discounts[].entity | string | Entidade que recebe o desconto |
discounts[].itemAmount | number | Quantidade mínima de itens para que o desconto em value seja aplicado |
discounts[].value | number | Valor do desconto aplicado quando itemAmount é atingido |
Parâmetros de Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
productId | integer | Sim | ID do produto base |
showcases | array | Sim | Tipos de vitrines a retornar |
showcases.* | string | Sim | Tipo: mainCategory, indicated, related |
fields | array | Não | Campos específicos do produto a retornar |
fields.* | string | Não | Nome do campo |
Tipos de Vitrine Disponíveis
| Tipo | Valor | Descrição |
|---|---|---|
| Categoria Principal | mainCategory | Produtos da mesma categoria principal |
| Indicados | indicated | Produtos indicados/sugeridos (upsell) |
| Relacionados | related | Produtos 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": null44 }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": null86 }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": null128 }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}