Valores de Filtros

Visão Geral

Os valores de filtros representam as opções disponíveis dentro de um filtro específico 🧩.

Eles são utilizados para definir quais alternativas o usuário poderá selecionar ao aplicar um filtro na loja, como por exemplo:

Cor → Vermelho, Azul, Preto
Tamanho → P, M, G
Voltagem → 110V, 220V

Cada valor pertence a um filtro e pode ser utilizado na associação com produtos, permitindo que os itens sejam exibidos corretamente quando um filtro é aplicado.

Além disso, os valores podem possuir ordenação personalizada e até mesmo imagens associadas, tornando a navegação mais clara e visual para o usuário.

Entidades Envolvidas

Filtro (Filter)

Valor do Filtro (Filter Value)

Produto (Product)

Imagem de Valor de Filtro

referência visual para o usuário

Notas e Considerações

Valores são normalmente utilizados em filtros como select ou múltipla escolha.
A ordem de exibição dos valores pode ser controlada pelo lojista.
Valores também podem possuir imagens associadas, muito utilizadas em filtros visuais como cores ou padrões.
Filtros do tipo text e bool não utilizam valores cadastrados previamente.

Cadastrar valores de filtros

POST /products/filters/{filterId}/values

Permite atribuir um valor a um filtro da loja

Descrição

Endpoint responsável por permitir que o lojista atribua múltiplos valores a um determinado filtro 🧩.

Atua em contexto administrativo, facilitando o gerenciamento dos valores disponíveis para cada filtro da loja.

Por meio desse endpoint, é possível cadastrar vários valores de uma só vez, funcionando como uma operação em lote, porém organizada por filtro.

Dessa forma, o lojista consegue configurar rapidamente os valores utilizados na filtragem de produtos, mantendo a navegação do catálogo mais estruturada e eficiente ⚙️.

⚠️ Atenção: filtros do tipo "text" e "bool" não podem possuir valores cadastrados.

Esses tipos de filtro devem possuir vínculo direto com o produto, sem a necessidade de definir valores previamente.

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	Sim	Identificador do filtro a receber novos valores

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅	Nome do valor do filtro
order	integer	✅	Determina ordenação dos valores
color	string	❌	Determina uma cor em hexadecimal para o valor

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/filters/{filterId}/values \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "values": [
6      {
7        "name": "Vermelho",
8        "order": 1,
9        "color": "#FF0000"
10      },
11      {
12        "name": "Azul",
13        "order": 2,
14        "color": "#1900ffff"
15      }
16    ]
17  }'
curl --request POST \
  --url {{MAIN_URL}}/products/filters/{filterId}/values \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "values": [
      {
        "name": "Vermelho",
        "order": 1,
        "color": "#FF0000"
      },
      {
        "name": "Azul",
        "order": 2,
        "color": "#1900ffff"
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  [
3		{
4			"id": 1,
5			"name": "Vermelho",
6			"image": "",
7			"originalImage": "",
8			"color": "#FF0000",
9			"order": 1,
10			"value": null
11		},
12		{
13			"id": 2,
14			"name": "Azul",
15			"image": "",
16			"originalImage": "",
17			"color": "#1900ffff",
18			"order": 2,
19			"value": null
20		}
21	]
22}
{
  [
		{
			"id": 1,
			"name": "Vermelho",
			"image": "",
			"originalImage": "",
			"color": "#FF0000",
			"order": 1,
			"value": null
		},
		{
			"id": 2,
			"name": "Azul",
			"image": "",
			"originalImage": "",
			"color": "#1900ffff",
			"order": 2,
			"value": null
		}
	]
}

⚠️ 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_DIRECT_FILTER_PRODUCT_LINK	400	O filtro requisitado deve ser vinculado diretamente para o produto.
UAPPI_STORE_FILTER_NOT_FOUND	404	O filtro solicitado não foi encontrado.

Atualizar valores de filtros

PUT /products/filters/values/{filterValueId}

Permite atualizar um valor já atribuído a um filtro da loja

Descrição

Endpoint responsável por permitir que o lojista atualize o valor de um determinado filtro 🔧.

Atua em contexto administrativo, possibilitando a edição de valores já cadastrados para os filtros da loja.

Por meio desse endpoint, é possível alterar as informações de um valor específico, realizando a atualização de forma individual (um valor por vez).

Isso permite ajustes pontuais e mais controlados, garantindo que os valores utilizados nos filtros permaneçam corretos e atualizados no catálogo ⚙️.

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
filterValueId	integer	Sim	Identificador do valor de filtro a ser atualizado

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅	Nome do valor do filtro
order	integer	✅	Determina ordenação dos valores
color	string	❌	Determina uma cor em hexadecimal para o valor

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/filters/values/{filterValueId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Vermelho",
6    "order": 1,
7    "color": "#FF0000"
8  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/filters/values/{filterValueId} \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Vermelho",
    "order": 1,
    "color": "#FF0000"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"id": 1,
3	"name": "Vermelho",
4	"image": "",
5	"originalImage": "",
6	"color": "#FF0000",
7	"order": 1,
8	"value": null
9}
{
	"id": 1,
	"name": "Vermelho",
	"image": "",
	"originalImage": "",
	"color": "#FF0000",
	"order": 1,
	"value": null
}

⚠️ Possíveis erros:

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

Cadastro de imagens para valores de filtros

POST /products/filters/values/{filterValueId}/image

Permite ao lojista atribuir imagens à valores de atributos

Descrição

Endpoint responsável por permitir que o lojista atribua imagens aos valores de atributos 🖼️.

Atua em contexto administrativo, possibilitando enriquecer visualmente os filtros utilizados na loja.

Por meio desse endpoint, é possível associar imagens aos valores de um filtro, fazendo com que o filtro passe a funcionar também como uma referência visual para o cliente final.

Isso é especialmente útil em cenários como cores, texturas ou variações visuais de produtos, tornando a navegação e seleção de filtros mais intuitiva e clara para quem está utilizando a loja ⚙️.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
filterValueId	integer	Sim	Identificador do valor de atributo que deve receber uma imagem

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`image`	file	✅	Imagem a ser enviada para o valor do filtro

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/filters/values/{filterValueId}/image \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --form 'image=@imagem.png' \
curl --request POST \
  --url {{MAIN_URL}}/products/filters/values/{filterValueId}/image \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --form 'image=@imagem.png' \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "name": "Outlet",
4  "image": "/upload/filter-value/987654321987654321987654321.webp",
5  "originalImage": "/upload/filter-value/987654321987654321987654321.jpeg",
6  "order": 1,
7  "value": null
8}
{
  "id": 1,
  "name": "Outlet",
  "image": "/upload/filter-value/987654321987654321987654321.webp",
  "originalImage": "/upload/filter-value/987654321987654321987654321.jpeg",
  "order": 1,
  "value": null
}

⚠️ Possíveis erros:

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

Vínculo de Filtros, Valores e Produtos

PUT /products/filters/values/link

Possibilita vincular filtros, valores e produtos

Descrição

Endpoint responsável por vincular filtros, valores e produtos 🔗.

Atua em contexto administrativo, permitindo que o lojista configure os filtros da loja com flexibilidade, podendo criar, atualizar ou remover vínculos entre essas entidades.

Por meio desse endpoint, é possível associar um produto a um filtro e ao valor correspondente, garantindo que as informações sejam corretamente utilizadas na filtragem e organização do catálogo.

Por que existe um campo para valor do filtro? 🤔

Mesmo já existindo valores cadastrados para filtros, alguns tipos possuem um comportamento diferente.

Filtros do tipo text e bool não permitem a criação de valores separadamente. Nesses casos, o valor do filtro é definido diretamente no vínculo com o produto.

Ou seja, ao criar o vínculo entre produto e filtro, também é informado qual valor aquele produto representa para o filtro.

Por esse motivo, ao cadastrar filtros desses tipos, o sistema pode retornar um erro indicando que o filtro deve possuir vínculo direto com o produto, já que seu valor será definido apenas nesse relacionamento ⚙️.

Flexibilidade na definição de valores: ainda assim, a definição de um valor não é obrigatória para o filtro.

Dessa forma, fica a critério do lojista definir como deseja estruturar e utilizar o filtro dentro do catálogo.

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
links	array	✅	Lista de vinculos que devem ser realizados
links.*.productId	integer	✅	Identificador do produto que deve ser vinculado a um filtro e valor
links.*.productFilterId	integer	✅	Identificador do filtro que deve ser vinculado a um produto e valor
links.*.productFilterValueId	integer	❌	Identificador do valor que deve ser vinculado a um produto e filtro
links.*.productFilterValueLinkId	integer	Obrigatório quando o campo action for "remove" ou "update"	Identificador do vínculo para cenários de atualização e exclusão de vínculos
links.*.action	string	✅	Tipo da ação que deve ser realizado (add, update, remove)
links.*.value	string	❌	Valor específico para um filtro

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/filters/values/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "links": [
6      {
7        "productId": 1,
8        "productFilterId": 1,
9        "productFilterValueId": 1,
10        "value": null,
11        "action": "add"
12      },
13      {
14        "productId": 2,
15        "productFilterId": 2,
16        "value": "350ml",
17        "action": "add"
18      }
19    ]
20  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/filters/values/link \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "links": [
      {
        "productId": 1,
        "productFilterId": 1,
        "productFilterValueId": 1,
        "value": null,
        "action": "add"
      },
      {
        "productId": 2,
        "productFilterId": 2,
        "value": "350ml",
        "action": "add"
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  [
3		{
4			"productId": 1,
5			"productFilterId": 1,
6			"productFilterValueId": 1,
7			"value": null,
8			"action": "add",
9			"error": null
10		},
11		{
12			"productId": 2,
13			"productFilterId": 2,
14			"productFilterValueId": null,
15			"value": "350ml",
16			"action": "add",
17			"error": null
18		}
19	]
20}
{
  [
		{
			"productId": 1,
			"productFilterId": 1,
			"productFilterValueId": 1,
			"value": null,
			"action": "add",
			"error": null
		},
		{
			"productId": 2,
			"productFilterId": 2,
			"productFilterValueId": null,
			"value": "350ml",
			"action": "add",
			"error": null
		}
	]
}

⚠️ 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_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_CATEGORY_NOT_FOUND	404	A categoria solicitada não foi encontrada.
UAPPI_STORE_MISMATCH_PRODUCT_CATEGORY_FILTER	404	O filtro solicitado não corresponde à categoria do produto.
UAPPI_STORE_FILTER_NOT_FOUND	404	O filtro solicitado não foi encontrado.
UAPPI_STORE_DIRECT_FILTER_PRODUCT_LINK	400	O filtro solicitado deve ser vinculado diretamente a um produto.
UAPPI_STORE_FILTER_VALUE_NOT_FOUND	404	O valor de filtro solicitado não foi encontrado.
UAPPI_STORE_INVALID_PRODUCT_FILTER_VALUE	400	O valor informado é inválido para o filtro espeecificado.

Atualizar ordenação dos valores de filtros

PUT /products/filters/{filterId}/values/order

Possibilita que o lojista possa definir a ordenação dos valores de um filtro

Descrição

Endpoint responsável por atualizar a ordenação dos valores de um determinado filtro 🔄.

Atua em contexto administrativo, permitindo que o lojista controle como os valores serão exibidos na loja.

Por meio desse endpoint, é possível definir a ordem de exibição dos valores do filtro, garantindo uma organização mais adequada para navegação e seleção.

Dessa forma, o lojista consegue priorizar valores mais relevantes ou utilizados, melhorando a experiência de uso dos filtros no catálogo ⚙️.

⚠️ Importante: a ordenação é definida pela posição dos IDs no array enviado na requisição.

Exemplo: considerando os valores de filtro com IDs 10, 15 e 20.

Se a requisição enviar:

1{
2  "ids": [15, 10, 20]
3}
{
  "ids": [15, 10, 20]
}

A ordem de exibição será:

1. Valor 15

2. Valor 10

3. Valor 20

Ou seja, a posição de cada ID dentro do array determina sua ordem final de exibição 📌.

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	Sim	Identificador do filtro ao qual os valores devem ser reordenados

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`ids`	array	✅	Lista de ids dos valores que devem ser reordenados
`ids.*`	integer	✅	Identificador do valor que deve ser reordenado

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/filters/{filterId}/values/order \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "ids": [
6      1, 2, 3
7    ]
8  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/filters/{filterId}/values/order \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "ids": [
      1, 2, 3
    ]
  }'

✅ 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."
  }
}

Exclusão de valores de filtros

DELETE /products/filters/values

Permite que o lojista possa remover valores de filtros

Descrição

Endpoint responsável por permitir que o lojista remova valores de atributos 🗑️.

Atua em contexto administrativo, possibilitando a exclusão de valores que não são mais necessários para determinado filtro.

Por meio desse endpoint, é possível remover valores previamente cadastrados, ajudando a manter a organização e a consistência das opções de filtragem do catálogo.

Dessa forma, o lojista consegue manter os atributos e filtros sempre atualizados, evitando valores obsoletos ou que não serão mais utilizados ⚙️.

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
`ids`	array	✅	Lista de ids dos valores de filtros que devem ser removidos
`ids.*`	integer	✅	Identificador do valor de filtro que deve ser ex

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/filters/values \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "ids": [
6      1, 2, 3
7    ]
8  }'
curl --request DELETE \
  --url {{MAIN_URL}}/products/filters/values \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "ids": [
      1, 2, 3
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true
true

Exclusão de imagens dos valores de filtros

DELETE /products/filters/values/{filterValueId}/image

Permite que o lojista possa remover imagens atribuidas a valores de filtros

Descrição

Endpoint responsável por permitir que o lojista remova imagens atribuídas aos valores de filtros 🗑️.

Atua em contexto administrativo, possibilitando a gestão das imagens associadas aos valores de atributos.

Por meio desse endpoint, é possível excluir imagens previamente vinculadas aos valores de filtros, permitindo ajustes ou correções na representação visual utilizada no catálogo.

Dessa forma, o lojista consegue manter as referências visuais sempre atualizadas, garantindo maior consistência na navegação e utilização dos filtros 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 da URL

Parâmetro	Tipo	Obrigatório	Descrição
filterValueId	integer	Sim	Identificador do valor de filtro ao qual a imagem deve ser removida

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/filters/values/{filterValueId}/image \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
curl --request DELETE \
  --url {{MAIN_URL}}/products/filters/values/{filterValueId}/image \
  --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_VALUE_NOT_FOUND",
6    "message": "The requested filter value was not found."
7  }
8}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_STORE_FILTER_VALUE_NOT_FOUND",
    "message": "The requested filter value 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

Valores de Filtros

Visão Geral

Entidades Envolvidas

Notas e Considerações

Cadastrar valores de filtros

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Atualizar valores de filtros

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cadastro de imagens para valores de filtros

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso