Documentações de Localizações

Visão Geral

A localização representa uma área específica da interface da loja, utilizada para organizar e controlar quais entidades devem ser exibidas em determinado ponto da aplicação 📍.

Em muitos cenários de e-commerce, não é trivial associar diretamente recursos como menus, banners ou vitrines a posições específicas do site.

Por isso, a localização funciona como um ponto intermediário de organização, permitindo vincular diferentes entidades a um mesmo identificador.

Quando o frontend consulta uma localização, o sistema pode retornar todas as entidades associadas a ela, permitindo que cada uma cumpra seu papel esperado na interface da loja.

Cada localização possui um identificador único, que deve ser informado utilizando letras maiúsculas e underscores (_) no lugar de espaços, garantindo padronização e fácil identificação dentro do sistema.

Além disso, cada localização define uma origem, que determina qual tipo de entidade poderá ser vinculada a ela.

Essa regra garante consistência estrutural e evita associações incompatíveis.

Entidades Relacionadas

Menus

As localizações podem ser utilizadas para definir onde um menu deve ser exibido dentro da interface da loja.

Isso permite que diferentes menus sejam apresentados em áreas distintas, como cabeçalho, rodapé ou menus laterais, de acordo com a estrutura definida pelo frontend.

Grupos de Banners

Grupos de banners também podem ser vinculados a uma localização.

Dessa forma, é possível determinar em quais áreas da loja determinados conjuntos de banners devem aparecer, facilitando a organização de campanhas e comunicações visuais.

Vitrines

As vitrines podem utilizar localizações para definir onde conjuntos de produtos devem ser exibidos.

Isso permite criar seções estratégicas dentro da loja, como produtos recomendados, lançamentos ou ofertas especiais, controladas pelo frontend.

Produtos de Upsell

Localizações também podem ser utilizadas para configurar áreas de upsell, exibindo produtos complementares ou recomendações relacionadas.

Essa estratégia permite aumentar o ticket médio da loja, apresentando sugestões relevantes em pontos específicos da jornada de compra.

Listagem de localizações

Descrição

Este endpoint retorna uma lista de localizações com base na origem informada no corpo da requisição.

O campo origem deve ser definido utilizando um dos valores permitidos: upsell, menu, banner ou showcase, garantindo que o retorno contenha apenas as localizações correspondentes ao tipo selecionado.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/template/location \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "origin": "menu"
6  }'

✅ Resposta de Sucesso

1{
2  "data": [
3		{
4			"id": "CHECKOUT_UPSELL",
5			"title": "Produtos de Upsell do checkout",
6			"description": "Exibe produtos de upsell no checkout baseado nos itens do carrinho",
7			"origin": "upsell",
8			"createdAt": "2026-02-12 13:21:21"
9		},
10		{
11			"id": "SHOWCASE_HOME",
12			"title": "Página inicial",
13			"description": "Vitrines dos produtos mais vendidos na página inicial",
14			"origin": "showcase",
15			"createdAt": "2026-02-11 18:45:20"
16		}
17  ]
18}

Cadastro de localização

Descrição

Este endpoint é responsável por permitir que o frontend configure localizações para controle de entidades da loja 📍.

A localização representa uma área específica da interface, funcionando como um ponto de associação para diferentes recursos da plataforma.

Ao configurar uma localização, é possível definir qual tipo de entidade poderá ser vinculada a ela, garantindo que o frontend consiga recuperar automaticamente os dados necessários para aquela área da loja.

O campo origem define qual entidade a localização deve atender, podendo assumir valores pré-definidos como menu, banner, showcase ou upsell.

O ID da localização deve ser informado utilizando apenas letras maiúsculas e underscores (_) no lugar de espaços, garantindo padronização no identificador.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/template/location \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "id":"MENU_PAGINA_INICIAL",
6    "title": "Página inicial",
7    "description": "Menus de navegação da página inicial",
8    "origin":"menu"
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "MENU_PAGINA_INICIAL",
3  "title": "Página inicial",
4  "description": "Menus de navegação da página inicial",
5  "origin": "menu",
6  "createdAt": ""
7}

⚠️ Erro retornado:

1{
2  "status": false,
3  "data": {
4    "code": 400,
5    "errorCode": "UAPPI_STORE_DUPLICATED_TEMPLATE_LOCATION",
6    "message": "The requested location id was already been used."
7  }
8}

Atualização de localização

Descrição

Este endpoint é responsável por atualizar as informações de título e descrição de uma localização. Para realizar a atualização, é necessário informar o ID da localização juntamente com a requisição na API, garantindo que os dados corretos sejam modificados.

Parâmetros do Corpo

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/template/location/{locationId}\
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

1{
2  "id": "CHECKOUT",
3  "title": "Carrinho do checkout",
4  "description": "Localização do carrinho no checkout",
5  "origin": "upsell",
6  "createdAt": "2026-02-12 13:21:21"
7}

⚠️ Erro retornado:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_TEMPLATE_LOCATION_NOT_FOUND",
6    "message": "A localização solicitada não foi encontrada."
7  }
8}

Excluir uma localização

Endpoint

Descrição

Este endpoint é responsável por excluir uma localização cadastrado, ação que deve ser realizada por um usuário autorizado. Após a exclusão, a localização não ficará mais disponível para consultas ou utilização na plataforma.

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/template/location/{locationId}\
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true