Documentação de Menus

Visão Geral

O menu é responsável por estruturar a navegação da loja, organizando links e acessos para as principais áreas da plataforma 🧭.

Por meio dos menus, é possível direcionar usuários para categorias, páginas, marcas, vitrines ou outras seções estratégicas, facilitando a descoberta de conteúdos e produtos.

Cada menu pode conter múltiplos itens de navegação, permitindo construir estruturas simples ou hierarquias mais completas, conforme a necessidade da loja.

Além disso, os menus podem ser vinculados a localizações específicas, possibilitando que diferentes menus sejam exibidos em áreas distintas da interface, como cabeçalho, rodapé ou menus laterais.

Entidades Relacionadas

Itens de Menu

Os itens de menu representam os elementos individuais de navegação dentro de um menu.

Cada item define o rótulo exibido ao usuário e o destino do link, podendo apontar para diferentes áreas da loja ou conteúdos específicos.

Essa estrutura permite organizar a navegação de forma flexível, criando desde menus simples até estruturas mais complexas de navegação.

Localização

O menu pode estar vinculado a uma localização específica.

As localizações são gerenciadas pelo frontend e permitem retornar um conjunto de entidades com base no local informado, determinando onde o menu deve ser exibido na interface.

Para mais informações sobre localizações, clique [aqui]({{ MAIN_URL }}/).

Cadastra itens de menu

Descrição

Este endpoint é responsável por cadastrar itens em um menu, que deve ser identificado pelo ID informado na URL da API.

Os itens cadastrados representam links ou entradas de navegação, podendo direcionar para páginas, categorias ou outras áreas da loja.

Com isso, é possível estruturar e personalizar a navegação do menu, facilitando o acesso dos usuários às principais seções da plataforma.

Tipo de Vínculo (type)

O campo type define o conteúdo ao qual o item estará vinculado e pode assumir os valores:

product, category, brand, page ou custom.

Essa definição impacta diretamente as validações da requisição, pois o endpoint aplica regras condicionais (required_if):

• product → obrigatório informar productId
• category → obrigatório informar productCategoryId
• brand → obrigatório informar productBrandId
• page → obrigatório informar productPageId
• custom → obrigatório informar customUrl

Os demais campos que não correspondem ao type informado não devem ser enviados.

Estrutura Hierárquica

O endpoint permite criar menus com múltiplos níveis. Para vincular o item como submenu de outro item existente, deve ser informado o campo templateMenuItemId com o ID do item pai.

Se esse campo for nulo ou não for informado, o item será criado como item de primeiro nível no menu.

Essa estrutura possibilita desde menus simples até composições mais complexas com múltiplos níveis de navegação.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/template/menus/{menuId}/items \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "templateMenuItemId": null,
6    "active": true,
7    "title": "Uappi",
8    "type": "brand",
9    "productBrandId": 1,
10    "highlight": true,
11    "target": "_blank"
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "templateMenuItemId": 0,
4  "active": true,
5  "title": "Titulo de item do menu",
6  "type": "brand",
7  "productId": null,
8  "productCategoryId": null,
9  "productBrandId": 1,
10  "productPageId": null,
11  "image1": "",
12  "image2": "",
13  "highlight": true,
14  "order": 0,
15  "url": "",
16  "target": "_blank",
17  "bannerGroups": [],
18  "items": []
19}

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

Atualização de um item de menu

Descrição

Este endpoint é responsável por atualizar itens de um menu existente ✏️.

Tanto o menu quanto o item que será atualizado devem ser identificados pelos respectivos IDs informados na URL da API, garantindo que a alteração seja aplicada ao registro correto.

Por meio dessa rota, é possível ajustar as configurações do item de menu, como rótulo, destino do link ou demais propriedades relacionadas à navegação.

Isso permite manter a estrutura do menu atualizada e alinhada à organização da loja 🧭.

Tipo de Vínculo (type)

O campo type define o conteúdo ao qual o item estará vinculado e pode assumir os valores:

product, category, brand, page ou custom.

Essa definição impacta diretamente as validações da requisição, pois o endpoint aplica regras condicionais (required_if):

• product → obrigatório informar productId
• category → obrigatório informar productCategoryId
• brand → obrigatório informar productBrandId
• page → obrigatório informar productPageId
• custom → obrigatório informar customUrl

Os demais campos que não correspondem ao type informado não devem ser enviados.

Estrutura Hierárquica

O endpoint permite criar menus com múltiplos níveis. Para vincular o item como submenu de outro item existente, deve ser informado o campo templateMenuItemId com o ID do item pai.

Se esse campo for nulo ou não for informado, o item será criado como item de primeiro nível no menu.

Essa estrutura possibilita desde menus simples até composições mais complexas com múltiplos níveis de navegação.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/template/menus/{menuId}/items/{menuItemId} \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "templateMenuItemId": null,
6    "active": true,
7    "title": "Uappi",
8    "type": "brand",
9    "productBrandId": 1,
10    "highlight": true,
11    "target": "_blank"
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "templateMenuItemId": 0,
4  "active": false,
5  "title": "Whey protein",
6  "type": "brand",
7  "productId": null,
8  "productCategoryId": null,
9  "productBrandId": 1,
10  "productPageId": null,
11  "image1": "",
12  "image2": "",
13  "highlight": true,
14  "order": 0,
15  "url": "",
16  "target": "_blank",
17  "bannerGroups": [],
18  "items": []
19}

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

Imagens de itens de menu

Descrição

Este endpoint é responsável por atualizar as imagens de itens de um menu.

Para cada item, é possível enviar até duas imagens por requisição, permitindo substituir ou atualizar os arquivos visuais associados.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/template/menus/{menuId}/items/{menuItemId}/image \
3  --header "Authorization: Bearer userToken" \
4  --form 'image1=@imagem.png' \
5  --form 'image2=@imagem.png' \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "image1": "/upload/menu/item/1.jpeg",
3	"image2": "/upload/menu/item/2.png"
4}

⚠️ Erro retornado:

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

Atualiza a ordem dos itens de um menu

Descrição

Este endpoint é responsável por ordenar os itens de um menu. O menu que terá sua ordem alterada deve ser identificado pelo ID informado na URL da API.

A ordem desejada dos itens deve ser enviada no corpo da requisição, informando os IDs de cada item na sequência correta, que será utilizada como referência para reorganizar a exibição no menu.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/template/menus/{menuId}/items/order \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "ids":[
6      1, 3, 2
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3	"data": true
4}

Exclusão de item de menu

Endpoint

Descrição

Este endpoint é responsável por excluir um item de um menu. Tanto o menu quanto o item que será removido devem ser identificados pelos respectivos IDs informados na URL da API, garantindo que a exclusão seja aplicada ao registro correto.

Parâmetros

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/template/menus/{menuId}/items/{menuItemId}\
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3	"data": true
4}