Listar Vitrines por Código

Retorna 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 banners.

> 📌 Importante: A API Uappi é self-hosted em cada loja. Substitua sua-loja.com.br pelo domínio real da loja que você está integrando.

Endpoint

GET /api/v3/publics/template/showcases

Obtém vitrines de produtos por códigos

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros de Query/Body

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 'https://sua-loja.com.br/api/v3/publics/template/showcases' \
3  --header 'Content-Type: application/json' \
4  --header 'uappi-cookie-name: uappi-cookie' \
5  --data '{
6    "codes": ["vitrine-lancamentos", "vitrine-mais-vendidos"],
7    "fields": ["price", "brand", "mainCategory", "media"]
8  }'
curl --request GET \
  --url 'https://sua-loja.com.br/api/v3/publics/template/showcases' \
  --header 'Content-Type: application/json' \
  --header 'uappi-cookie-name: uappi-cookie' \
  --data '{
    "codes": ["vitrine-lancamentos", "vitrine-mais-vendidos"],
    "fields": ["price", "brand", "mainCategory", "media"]
  }'

Respostas

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":09",
46					"updatedAt":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}
{
  "status": true,
  "data": [
    {
      "id": 1,
      "code": "vitrine-lancamentos",
      "name": "Lançamentos",
      "title": "Últimos Lançamentos",
      "description": "Produtos recém-chegados à loja",
      "bannerGroups": ["banner-lancamentos"],
      "products": [
        {
					"id": 44,
					"type": "product",
					"sku": "ABC123",
					"name": "TechBrand Smartphone",
					"priority": 1,
					"basePrice": 1199,
					"active": true,
					"review": null,
					"isGiftCard": false,
					"stock": null,
					"stocks": null,
					"originalPrice": null,
					"price": null,
					"priceRules": null,
					"brand": null,
					"flags": null,
					"tax": null,
					"indicatedProducts": null,
					"relatedProducts": null,
					"filters": null,
					"seals": null,
					"mainCategory": null,
					"categories": null,
					"categoryBreadcrumb": null,
					"dimensions": null,
					"parentProductId": null,
					"combination": [],
					"currentAttributes": null,
					"variations": null,
					"medias": null,
					"bannerGroups": [],
					"status": null,
					"createdAt": "2022-10-03 17:28:09",
					"updatedAt": "2025-09-23 01:31:32",
					"url": "",
					"urls": [],
					"linkedTradePolicies": null,
					"description": null
				},
        "pagination": {
          "limit": 12,
          "offset": 0,
          "pages": 1,
          "registers": 8
        }
      ]
    }
  ]
}

Possíveis Erros

#### Vitrine Não Encontrada

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}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_SHOWCASE_NOT_FOUND",
    "message": "Showcase not found with the provided codes."
  }
}

#### Validação de Parâmetros

1{
2  "status": false,
3  "data": {
4    "code": 422,
5    "errorCode": "VALIDATION_ERROR",
6    "message": "The codes field is required."
7  }
8}
{
  "status": false,
  "data": {
    "code": 422,
    "errorCode": "VALIDATION_ERROR",
    "message": "The codes field is required."
  }
}

Códigos de Status

Código	Descrição
200	Vitrines retornadas com sucesso
404	Nenhuma vitrine encontrada com os códigos fornecidos
422	Erro de validação nos parâmetros da requisição
500	Erro interno do servidor

Campos Retornados

Vitrine (PublicShowcaseDMC)

Campo	Tipo	Descrição
`id`	integer	ID da vitrine
`code`	string	Código único da vitrine
`name`	string	Nome da vitrine
`title`	string	Título exibido da vitrine
`description`	string	Descrição da vitrine
`bannerGroups`	array	Códigos de grupos de banners relacionados
`products`	object	Objeto com produtos e paginação

Estrutura de Produtos

Campo	Tipo	Descrição
`registers`	array	Lista de produtos da vitrine
`pagination`	object	Informações de paginação
`pagination.limit`	integer	Limite de produtos por página
`pagination.offset`	integer	Deslocamento atual
`pagination.pages`	integer	Total de páginas
`pagination.registers`	integer	Total de produtos

Funcionalidades Especiais

Produtos Mais Vendidos

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

Considera apenas pedidos com status: PAID, INVOICED, SENT, DELIVERED
Limita a 1000 produtos mais vendidos
Ordena por quantidade total vendida (maior para menor)

Filtros e Ordenações Personalizadas

Cada vitrine pode ter:

Filtros (condition): Regras personalizadas de filtragem de produtos
Ordenação (order): Critérios de ordenação específicos
Limite: Quantidade máxima de produtos a retornar

Integração com Banners

O campo bannerGroups contém códigos de grupos de banners que podem ser exibidos junto à vitrine.

Parâmetro `fields`

Use o parâmetro fields para otimizar a resposta, retornando apenas os campos necessários:

Campos Disponíveis (CompleteProductDMC):

Leves 🟢:

brand, description, mainCategory, dimension, mainUrl, secondaryUrls, flags, tax, status

Médios 🟡:

price, categories, categoryBreadcrumb, media, seals, filters, priceRule, review, bannerGroup

Pesados 🔴:

stockByStorage, variation, pairOffer, indicatedProducts, relatedProducts

Exemplo de Uso com Fields

1{
2  "codes": ["vitrine-home"],
3  "fields": ["price", "brand", "media", "mainUrl"]
4}
{
  "codes": ["vitrine-home"],
  "fields": ["price", "brand", "media", "mainUrl"]
}

Observações

Vitrines Dinâmicas: Produtos são buscados em tempo real com base nas regras configuradas
Trade Policy: Produtos respeitam a política comercial do canal
Cache: Recomenda-se cache no frontend para vitrines de homepage
Performance: Use fields para carregar apenas dados necessários
Estoque: Produtos sem estoque podem ser filtrados nas regras da vitrine
Agendamento: Vitrines podem ter agendamento de exibição configurado no admin

Casos de Uso

Homepage

1{
2  "codes": ["vitrine-destaque", "vitrine-lancamentos", "vitrine-ofertas"],
3  "fields": ["price", "media", "mainUrl", "brand"]
4}
{
  "codes": ["vitrine-destaque", "vitrine-lancamentos", "vitrine-ofertas"],
  "fields": ["price", "media", "mainUrl", "brand"]
}

Página de Categoria

1{
2  "codes": ["vitrine-relacionados"],
3  "fields": ["price", "media", "mainUrl", "review"]
4}
{
  "codes": ["vitrine-relacionados"],
  "fields": ["price", "media", "mainUrl", "review"]
}

Email Marketing

1{
2  "codes": ["vitrine-recomendados-email"],
3  "fields": ["price", "media", "name", "mainUrl"]
4}
{
  "codes": ["vitrine-recomendados-email"],
  "fields": ["price", "media", "name", "mainUrl"]
}

Listar Vitrines por Produto

Retorna vitrines de produtos automaticamente geradas com base em um produto específico. Permite obter produtos relacionados, produtos indicados (upsell) ou produtos da mesma categoria principal.

> 📌 Importante: A API Uappi é self-hosted em cada loja. Substitua sua-loja.com.br pelo domínio real da loja que você está integrando.

Endpoint

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

Obtém vitrines relacionadas a um produto específico

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros de Rota

Parâmetro	Tipo	Obrigatório	Descrição
`productId`	integer	Sim	ID do produto base

Parâmetros de Query/Body

Parâmetro	Tipo	Obrigatório	Descrição
`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 'https://sua-loja.com.br/api/v3/publics/template/showcases/1001' \
3  --header 'Content-Type: application/json' \
4  --header 'uappi-cookie-name: uappi-cookie' \
5  --data '{
6    "showcases": ["mainCategory", "indicated", "related"],
7    "fields": ["price", "brand", "media", "mainUrl"]
8  }'
curl --request GET \
  --url 'https://sua-loja.com.br/api/v3/publics/template/showcases/1001' \
  --header 'Content-Type: application/json' \
  --header 'uappi-cookie-name: uappi-cookie' \
  --data '{
    "showcases": ["mainCategory", "indicated", "related"],
    "fields": ["price", "brand", "media", "mainUrl"]
  }'

Respostas

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":12",
39				"updatedAt":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":12",
81				"updatedAt":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":12",
123				"updatedAt":42",
124				"url": "",
125				"urls": [],
126				"linkedTradePolicies": null,
127				"description": null
128			}
129    ]
130  }
131}
{
  "status": true,
  "data": {
    "mainCategory": [
      {
				"id": 123,
				"type": "product",
				"sku": "ABC123",
				"name": "Smartphone TechBrand 123",
				"priority": 1,
				"basePrice": 1199,
				"active": true,
				"review": null,
				"isGiftCard": false,
				"stock": null,
				"stocks": null,
				"originalPrice": null,
				"price": null,
				"priceRules": null,
				"brand": null,
				"flags": null,
				"tax": null,
				"indicatedProducts": null,
				"relatedProducts": null,
				"filters": null,
				"seals": null,
				"mainCategory": null,
				"categories": null,
				"categoryBreadcrumb": null,
				"dimensions": null,
				"parentProductId": null,
				"combination": [],
				"currentAttributes": null,
				"variations": null,
				"medias": null,
				"bannerGroups": [],
				"status": null,
				"createdAt": "2022-12-13 14:44:12",
				"updatedAt": "2025-09-17 14:11:42",
				"url": "",
				"urls": [],
				"linkedTradePolicies": null,
				"description": null
			}
    ],
    "indicated": [
      {
				"id": 1235,
				"type": "product",
				"sku": "ABC321",
				"name": "Smartphone TechBrand 321",
				"priority": 2,
				"basePrice": 1199,
				"active": true,
				"review": null,
				"isGiftCard": false,
				"stock": null,
				"stocks": null,
				"originalPrice": null,
				"price": null,
				"priceRules": null,
				"brand": null,
				"flags": null,
				"tax": null,
				"indicatedProducts": null,
				"relatedProducts": null,
				"filters": null,
				"seals": null,
				"mainCategory": null,
				"categories": null,
				"categoryBreadcrumb": null,
				"dimensions": null,
				"parentProductId": null,
				"combination": [],
				"currentAttributes": null,
				"variations": null,
				"medias": null,
				"bannerGroups": [],
				"status": null,
				"createdAt": "2022-12-13 14:44:12",
				"updatedAt": "2025-09-17 14:11:42",
				"url": "",
				"urls": [],
				"linkedTradePolicies": null,
				"description": null
			}
    ],
    "related": [
{
				"id": 1236,
				"type": "product",
				"sku": "ABC456",
				"name": "Smartphone TechBrand 456",
				"priority": 3,
				"basePrice": 1199,
				"active": true,
				"review": null,
				"isGiftCard": false,
				"stock": null,
				"stocks": null,
				"originalPrice": null,
				"price": null,
				"priceRules": null,
				"brand": null,
				"flags": null,
				"tax": null,
				"indicatedProducts": null,
				"relatedProducts": null,
				"filters": null,
				"seals": null,
				"mainCategory": null,
				"categories": null,
				"categoryBreadcrumb": null,
				"dimensions": null,
				"parentProductId": null,
				"combination": [],
				"currentAttributes": null,
				"variations": null,
				"medias": null,
				"bannerGroups": [],
				"status": null,
				"createdAt": "2022-12-13 14:44:12",
				"updatedAt": "2025-09-17 14:11:42",
				"url": "",
				"urls": [],
				"linkedTradePolicies": null,
				"description": null
			}
    ]
  }
}

Possíveis Erros

#### Produto Não Encontrado

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

#### Tipo de Vitrine Inválido

1{
2  "status": false,
3  "data": {
4    "code": 422,
5    "errorCode": "VALIDATION_ERROR",
6    "message": "The selected showcases.0 is invalid."
7  }
8}
{
  "status": false,
  "data": {
    "code": 422,
    "errorCode": "VALIDATION_ERROR",
    "message": "The selected showcases.0 is invalid."
  }
}

#### Validação de Parâmetros

1{
2  "status": false,
3  "data": {
4    "code": 422,
5    "errorCode": "VALIDATION_ERROR",
6    "message": "The showcases field is required."
7  }
8}
{
  "status": false,
  "data": {
    "code": 422,
    "errorCode": "VALIDATION_ERROR",
    "message": "The showcases field is required."
  }
}

Códigos de Status

Código	Descrição
200	Vitrines retornadas com sucesso
404	Produto não encontrado
422	Erro de validação nos parâmetros
500	Erro interno do servidor

Estrutura de Retorno

A resposta retorna um objeto onde cada chave é o tipo de vitrine solicitado e o valor contém:

Estrutura por Tipo

1{
2  "mainCategory": {     // ou "indicated", "related"
3    "registers": [],    // Array de produtos
4    "pagination": {}    // Informações de paginação
5  }
6}
{
  "mainCategory": {     // ou "indicated", "related"
    "registers": [],    // Array de produtos
    "pagination": {}    // Informações de paginação
  }
}

Campos de Paginação

Campo	Tipo	Descrição
`limit`	integer	Limite de produtos (fixo em 15)
`offset`	integer	Deslocamento atual
`pages`	integer	Total de páginas
`registers`	integer	Total de produtos

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
Útil para "Outros produtos desta categoria"

2. Produtos Indicados (`indicated`)

Retorna produtos cadastrados como "indicados" no produto base
Configurado no admin: Produto → Produtos Indicados
Ideal para upsell e cross-sell

3. Produtos Relacionados (`related`)

Retorna produtos cadastrados como "relacionados" no produto base
Configurado no admin: Produto → Produtos Relacionados
Útil para "Compre Junto" ou "Produtos Similares"

Observações

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

Casos de Uso

Página de Produto - Seção "Quem viu, viu também"

1{
2  "showcases": ["mainCategory"],
3  "fields": ["price", "media", "mainUrl", "name"]
4}
{
  "showcases": ["mainCategory"],
  "fields": ["price", "media", "mainUrl", "name"]
}

Página de Produto - Upsell no Carrinho

1{
2  "showcases": ["indicated"],
3  "fields": ["price", "media", "mainUrl", "name", "stock"]
4}
{
  "showcases": ["indicated"],
  "fields": ["price", "media", "mainUrl", "name", "stock"]
}

Página de Produto - Cross-sell Completo

1{
2  "showcases": ["indicated", "related", "mainCategory"],
3  "fields": ["price", "brand", "media", "mainUrl"]
4}
{
  "showcases": ["indicated", "related", "mainCategory"],
  "fields": ["price", "brand", "media", "mainUrl"]
}

Email de Abandono de Carrinho

1{
2  "showcases": ["related"],
3  "fields": ["price", "media", "name", "mainUrl"]
4}
{
  "showcases": ["related"],
  "fields": ["price", "media", "name", "mainUrl"]
}

Integração com Frontend

1// Exemplo de renderização
2const showcases = response.data;
3
4// Produtos da mesma categoria
5if (showcases.mainCategory?.registers.length > 0) {
6  renderShowcase('Produtos da Mesma Categoria', showcases.mainCategory.registers);
7}
8
9// Produtos indicados (upsell)
10if (showcases.indicated?.registers.length > 0) {
11  renderShowcase('Complete sua Compra', showcases.indicated.registers);
12}
13
14// Produtos relacionados
15if (showcases.related?.registers.length > 0) {
16  renderShowcase('Produtos Similares', showcases.related.registers);
17}
// Exemplo de renderização
const showcases = response.data;
// Produtos da mesma categoria
if (showcases.mainCategory?.registers.length > 0) {
  renderShowcase('Produtos da Mesma Categoria', showcases.mainCategory.registers);
}
// Produtos indicados (upsell)
if (showcases.indicated?.registers.length > 0) {
  renderShowcase('Complete sua Compra', showcases.indicated.registers);
}
// Produtos relacionados
if (showcases.related?.registers.length > 0) {
  renderShowcase('Produtos Similares', showcases.related.registers);
}

Prologue

Getting Started

Architecture Concepts

The Basics

Digging Deeper

Security

Database

Eloquent ORM

Testing

Packages

Listar Vitrines por Código

Endpoint

Parâmetros

Headers Obrigatórios

Parâmetros de Query/Body

Exemplo de Requisição

Respostas

Resposta de Sucesso

Possíveis Erros

Códigos de Status

Campos Retornados

Vitrine (PublicShowcaseDMC)

Estrutura de Produtos

Funcionalidades Especiais

Produtos Mais Vendidos

Filtros e Ordenações Personalizadas

Integração com Banners

Parâmetro fields

Campos Disponíveis (CompleteProductDMC):

Exemplo de Uso com Fields

Observações

Casos de Uso

Homepage

Página de Categoria

Email Marketing

Listar Vitrines por Produto

Endpoint

Parâmetros

Headers Obrigatórios

Parâmetros de Rota

Parâmetros de Query/Body

Tipos de Vitrine Disponíveis

Exemplo de Requisição

Respostas

Resposta de Sucesso

Possíveis Erros

Códigos de Status

Estrutura de Retorno

Estrutura por Tipo

Campos de Paginação

Lógica de Cada Tipo de Vitrine

1. Categoria Principal (mainCategory)

2. Produtos Indicados (indicated)

3. Produtos Relacionados (related)

Observações

Casos de Uso

Página de Produto - Seção "Quem viu, viu também"

Página de Produto - Upsell no Carrinho

Página de Produto - Cross-sell Completo

Email de Abandono de Carrinho

Integração com Frontend

Nesta página

Products

Packages

Resources

Parâmetro `fields`

1. Categoria Principal (`mainCategory`)

2. Produtos Indicados (`indicated`)

3. Produtos Relacionados (`related`)