Filtros de Produtos

Visão Geral

Os filtros são mecanismos utilizados para refinar a busca e navegação de produtos dentro da loja 🔎.

Eles permitem que os clientes encontrem produtos com mais facilidade, aplicando critérios específicos como marca, cor, tamanho, material, voltagem, entre outros atributos.

No contexto administrativo, os filtros são configurados pelo lojista, que define quais filtros existirão na loja, como eles serão exibidos e em quais categorias poderão ser utilizados.

Além disso, cada filtro pode possuir diferentes tipos de comportamento, como filtros baseados em valores pré-definidos ou filtros cujo valor é definido diretamente no vínculo com o produto.

Dessa forma, os filtros contribuem para uma navegação mais organizada, intuitiva e eficiente dentro do catálogo.

Entidades Envolvidas

Filtro (Filter)

Valor do Filtro (Filter Value)

Produto (Product)

Categoria (Category)

Notas e Considerações

Filtros podem possuir diferentes tipos, como enum, array, text e bool.
Filtros do tipo text e bool não possuem valores cadastrados previamente.
Nesses casos, o valor do filtro é definido diretamente no vínculo com o produto.

Listagem de Filtros da loja

GET /products/filters

Possibilita que o lojista possa visualizar os filtros cadastrados na loja

Descrição

Endpoint responsável por retornar uma lista paginada de filtros cadastrados na loja 🏷️.

Permite que o lojista consulte os filtros existentes e gerencie suas configurações, facilitando a organização e manutenção dos filtros utilizados na navegação dos produtos.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Campos Disponíveis (fields)

Campo	Descrição
values	Carrega os valores do filtro (filtro cor -> valores (azul, vermelho, verde, etc.))

Campos de Condição Disponíveis

Campo	Tipo	Descrição
productCategoryId	integer	Identificador da categoria associada ao filtro
active	boolean	Status de ativação do filtro
showInListing	boolean	Determina se o filtro deve ser exibido na listagem
showInSpecificationTable	boolean	Determina se o filtro deve ser exibido na tabela de especificação técnica do produto
type	enum	Determina qual o tipo do filtro (array, enum, text, bool)
name	string	Nome de exibição do filtro

Campos de Ordenação Disponíveis

Campo	Descrição
id	Identificador do filtro
createdAt	Data de cadastro do filtro

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/filters \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
curl --request GET \
  --url {{MAIN_URL}}/products/filters \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "productCategoryId": 1,
6      "name": "Cor:",
7      "active": true,
8      "showInListing": true,
9      "showInSpecificationTable": true,
10      "type": "enum",
11      "createdAt": "2025-08-10 15:27:44",
12      "values": [
13        {
14          "id": 1,
15          "name": "Azul",
16          "image": null,
17          "originalImage": null,
18          "color": null,
19          "order": 0,
20          "value": null
21        },
22        {
23          "id": 2,
24          "name": "Branco",
25          "image": null,
26          "originalImage": null,
27          "color": null,
28          "order": 0,
29          "value": null
30        },
31        {
32          "id": 3,
33          "name": "Preto",
34          "image": null,
35          "originalImage": null,
36          "color": null,
37          "order": 0,
38          "value": null
39        }
40      ]
41    }
42  ],
43  "pagination": {
44    "limit": 10,
45    "offset": 0,
46    "pages": 1,
47    "registers": 10
48  }
49}
{
  "registers": [
    {
      "id": 1,
      "productCategoryId": 1,
      "name": "Cor:",
      "active": true,
      "showInListing": true,
      "showInSpecificationTable": true,
      "type": "enum",
      "createdAt": "2025-08-10 15:27:44",
      "values": [
        {
          "id": 1,
          "name": "Azul",
          "image": null,
          "originalImage": null,
          "color": null,
          "order": 0,
          "value": null
        },
        {
          "id": 2,
          "name": "Branco",
          "image": null,
          "originalImage": null,
          "color": null,
          "order": 0,
          "value": null
        },
        {
          "id": 3,
          "name": "Preto",
          "image": null,
          "originalImage": null,
          "color": null,
          "order": 0,
          "value": null
        }
      ]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 10
  }
}

Listagem de Filtros por categorias

GET /products/filters/list-by-category

Retorna lista de filtros da loja por categoria

Descrição

Endpoint responsável por visualizar a lista de filtros da loja organizados por categorias 🏷️.

Permite que o lojista consulte quais filtros estão associados a cada categoria, facilitando a gestão e a organização da navegação dos produtos na loja.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
categoriesIds	array	✅	Lista de ids de categorias para buscar os filtros associados
categoriesIds.*	integer	✅	Identificador da categoria para consultar os filtros associados

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/filters/list-by-category \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "categoriesIds": [
6      1, 2, 3
7    ]
8  }'
curl --request GET \
  --url {{MAIN_URL}}/products/filters/list-by-category \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "categoriesIds": [
      1, 2, 3
    ]
  }'

✅ Resposta de Sucesso

1{
2  "id": 1,
3  "name": "Smartphones",
4  "url": "smartphones",
5  "filters": [
6    {
7      "id": 1,
8      "productCategoryId": 1,
9      "name": "Cor",
10      "active": true,
11      "showInListing": false,
12      "showInSpecificationTable": true,
13      "type": "enum",
14      "createdAt": "2026-03-12 19:46:14",
15      "values": []
16    }
17  ]
18}
{
  "id": 1,
  "name": "Smartphones",
  "url": "smartphones",
  "filters": [
    {
      "id": 1,
      "productCategoryId": 1,
      "name": "Cor",
      "active": true,
      "showInListing": false,
      "showInSpecificationTable": true,
      "type": "enum",
      "createdAt": "2026-03-12 19:46:14",
      "values": []
    }
  ]
}

Busca detalhes de um filtro da loja

GET /products/filters/{filterId}

Possibilita que o lojista veja detalhes de um filtro cadastrado na loja

Descrição

Endpoint responsável por visualizar os detalhes de um filtro da loja 🔎.

Permite que o lojista consulte suas configurações e ajuste as informações conforme necessário, garantindo que o filtro esteja corretamente configurado para uso nas categorias e na navegação dos produtos.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
filterId	integer	✅	Identificador do filtro que deve ser consultado

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/filters/{filterId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
curl --request GET \
  --url {{MAIN_URL}}/products/filters/{filterId} \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"id": 1,
5		"productCategoryId": 1,
6		"name": "Cor:",
7		"active": true,
8		"showInListing": true,
9		"showInSpecificationTable": true,
10		"type": "enum",
11		"createdAt": "2025-08-10 15:27:44",
12		"values": [
13			{
14				"id": 1,
15				"name": "Azul",
16				"image": null,
17				"originalImage": null,
18				"color": null,
19				"order": 0,
20				"value": null
21			},
22			{
23				"id": 2,
24				"name": "Branco",
25				"image": null,
26				"originalImage": null,
27				"color": null,
28				"order": 0,
29				"value": null
30			},
31			{
32				"id": 3,
33				"name": "Preto",
34				"image": null,
35				"originalImage": null,
36				"color": null,
37				"order": 0,
38				"value": null
39			}
40		]
41	}
42}
{
	"status": true,
	"data": {
		"id": 1,
		"productCategoryId": 1,
		"name": "Cor:",
		"active": true,
		"showInListing": true,
		"showInSpecificationTable": true,
		"type": "enum",
		"createdAt": "2025-08-10 15:27:44",
		"values": [
			{
				"id": 1,
				"name": "Azul",
				"image": null,
				"originalImage": null,
				"color": null,
				"order": 0,
				"value": null
			},
			{
				"id": 2,
				"name": "Branco",
				"image": null,
				"originalImage": null,
				"color": null,
				"order": 0,
				"value": null
			},
			{
				"id": 3,
				"name": "Preto",
				"image": null,
				"originalImage": null,
				"color": null,
				"order": 0,
				"value": null
			}
		]
	}
}

⚠️ Possíveis erros:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_FILTER_NOT_FOUND",
6    "message": "The requested filter was not found."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_FILTER_NOT_FOUND",
    "message": "The requested filter was not found."
  }
}

Cadastro de filtros

POST /products/filters

Possibilita que o lojista possa cadastrar os filtros da loja

Descrição

Endpoint responsável por cadastrar filtros personalizados associados a categorias de produtos na loja 🏷️.

Permite que o lojista defina atributos que poderão ser utilizados tanto para filtragem na navegação dos produtos quanto para exibição de informações técnicas na página do produto.

Através deste endpoint é possível configurar o nome do filtro, seu status de ativação, o tipo de dado esperado e onde ele será exibido na loja, como em listagens de produtos ou na tabela de especificações técnicas.

Essa configuração permite que cada categoria possua filtros próprios, adaptados às características dos produtos. Isso facilita a navegação dos clientes e torna a visualização das informações mais organizada.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
productCategoryId	integer	✅	Identificador da categoria que deve ser associada ao filtro
name	string	✅	Nome de exibição do filtro na loja
active	boolean	✅	Status de ativação do filtro
showInListing	boolean	✅	Determina se o filtro deve ser exibido em listagem
showInSpecificationTable	boolean	✅	Determina se o filtro deve ser exibido na tabela técnica de especificação do produto
type	string	✅	Determina o tipo de filtro (array, enum, text, bool)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/filters \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productCategoryId": 1,
6    "name": "Cor",
7    "active": true,
8    "showInListing": false,
9    "showInSpecificationTable": true,
10    "type": "array"
11  }'
curl --request POST \
  --url {{MAIN_URL}}/products/filters \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productCategoryId": 1,
    "name": "Cor",
    "active": true,
    "showInListing": false,
    "showInSpecificationTable": true,
    "type": "array"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "productCategoryId": 1,
4  "name": "Cor",
5  "active": true,
6  "showInListing": false,
7  "showInSpecificationTable": true,
8  "type": "array",
9  "createdAt": "2026-03-12 19:46:14",
10  "values": []
11}
{
  "id": 1,
  "productCategoryId": 1,
  "name": "Cor",
  "active": true,
  "showInListing": false,
  "showInSpecificationTable": true,
  "type": "array",
  "createdAt": "2026-03-12 19:46:14",
  "values": []
}

⚠️ Possíveis erros:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_CATEGORY_NOT_FOUND",
6    "message": "The requested category was not found."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_CATEGORY_NOT_FOUND",
    "message": "The requested category was not found."
  }
}

Atualização de filtros

PUT /products/filters/{filterId}

Possibilita que o lojista possa atualizar os filtros da loja

Descrição

Endpoint responsável por permitir que o lojista atualize filtros existentes da loja 🔧.

Atua em contexto administrativo, possibilitando a modificação das configurações associadas aos filtros do catálogo.

Por meio desse endpoint, é possível editar informações já cadastradas, como nome, status e demais parâmetros de funcionamento do filtro.

Dessa forma, o lojista consegue ajustar e manter os filtros atualizados, garantindo que a navegação e a busca por produtos continuem organizadas e eficientes na loja ⚙️.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
productCategoryId	integer	✅	Identificador da categoria que deve ser associada ao filtro
name	string	✅	Nome de exibição do filtro na loja
active	boolean	✅	Status de ativação do filtro
showInListing	boolean	✅	Determina se o filtro deve ser exibido em listagem
showInSpecificationTable	boolean	✅	Determina se o filtro deve ser exibido na tabela técnica de especificação do produto

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/filters/{filterId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productCategoryId": 1,
6    "name": "Cor",
7    "active": true,
8    "showInListing": false,
9    "showInSpecificationTable": true
10  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/filters/{filterId} \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productCategoryId": 1,
    "name": "Cor",
    "active": true,
    "showInListing": false,
    "showInSpecificationTable": true
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "productCategoryId": 1,
4  "name": "Cor",
5  "active": true,
6  "showInListing": false,
7  "showInSpecificationTable": true,
8  "type": "array",
9  "createdAt": "2026-03-12 19:46:14",
10  "values": []
11}
{
  "id": 1,
  "productCategoryId": 1,
  "name": "Cor",
  "active": true,
  "showInListing": false,
  "showInSpecificationTable": true,
  "type": "array",
  "createdAt": "2026-03-12 19:46:14",
  "values": []
}

⚠️ 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.

Código Interno	Código Http	Descrição
UAPPI_STORE_CATEGORY_NOT_FOUND	404	The requested category was not found.
UAPPI_STORE_FILTER_NOT_FOUND	404	The requested filter was not found.

Exclusão de filtros

DELETE /products/filters/{filterId}

Permite a exclusão de filtros da loja

Descrição

Endpoint responsável por permitir que o lojista exclua filtros cadastrados na loja 🗑️.

Atua em contexto administrativo, possibilitando a remoção de filtros que não são mais necessários no catálogo.

Por meio desse endpoint, é possível eliminar filtros indesejados ou obsoletos, ajudando a manter a organização das opções de navegação da loja.

Dessa forma, o lojista consegue manter os filtros sempre atualizados e relevantes, garantindo uma experiência de busca mais clara e eficiente para os usuários ⚙️.

⚠️ Atenção: ao utilizar este endpoint, os valores do filtro também serão excluídos, juntamente com todas as imagens vinculadas a esses valores.

Essa ação remove completamente os dados associados ao filtro, portanto deve ser utilizada com cautela para evitar a perda de informações importantes.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
filterId	integer	Sim	Identificador do filtro a ser excluído

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/filters/{filterId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
curl --request POST \
  --url {{MAIN_URL}}/products/filters/{filterId} \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true
true

⚠️ Possíveis erros:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_FILTER_NOT_FOUND",
6    "message": "The requested filter was not found."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_FILTER_NOT_FOUND",
    "message": "The requested filter was not found."
  }
}

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Filtros de Produtos

Visão Geral

Entidades Envolvidas

Notas e Considerações

Listagem de Filtros da loja

Descrição

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

Listagem de Filtros por categorias

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

Busca detalhes de um filtro da loja

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cadastro de filtros

Descrição