API atual/Referência completa/Menus de navegação

Itens do menu

Cria, altera, exclui e reordena os itens (links) de um menu de navegação.

Os itens são os links do menu. Eles formam uma árvore: um item pode ter filhos (um submenu), até 5 níveis. Todas as rotas exigem o privilégio manage_layouts.

Criar item

POST/api/v1/admin/navigation/menus/{id}/itemsAdmin

Adiciona um item a um menu

Se você não enviar position (ou enviar 0), o item vai para o fim da lista de irmãos. O item nasce ativo. Para category, product e page, o reference_id precisa existir; para custom_link, a url precisa começar com /, http:// ou https://.

Parâmetros de caminho

iduuidobrigatório

Id do menu.

Corpo da requisição

labelstringobrigatório

Texto do link. Não pode ser vazio nem só espaços.

item_typestringobrigatório

categorypageproductcustom_link

Tipo do item.

reference_iduuid

Id da categoria, produto ou página. Obrigatório nos três tipos de referência.

urlstring

Endereço do link. Obrigatório em custom_link.

parent_item_iduuid

Item pai, para criar um submenu. Respeita o limite de 5 níveis e não permite ciclo.

positionintegerpadrão: fim

Ordem entre os irmãos, a partir de 0. Com 0 ou omitido vai para o fim.

open_in_new_tabbooleanpadrão: false

Abrir em nova aba.

css_classstring

Classe CSS extra.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/navigation/menus/$MENU_ID/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Fale conosco","item_type":"custom_link","url":"/contato"}'

201Item criado

json

{
  "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "menu_id": "b4d75fb9-9e16-4efa-b15d-5b5547af37fb",
  "label": "Fale conosco",
  "url": "/contato",
  "item_type": "custom_link",
  "position": 5,
  "open_in_new_tab": false,
  "status": "A",
  "created_at": "2026-10-11T18:10:00.000Z",
  "updated_at": "2026-10-11T18:10:00.000Z"
}

Alterar item

PUT/api/v1/admin/navigation/items/{id}Admin

Altera um item do menu

Alteração parcial; envie ao menos um campo. Mande parent_item_id vazio ("") para tornar o item de primeiro nível; o mesmo vale para limpar reference_id e css_class. Diferente da criação, esta rota não revalida a url nem o reference_id.

Parâmetros de caminho

iduuidobrigatório

Id do item.

Corpo da requisição

labelstring

Novo texto.

urlstring

Novo endereço.

item_typestring

categorypageproductcustom_link

Novo tipo.

reference_idstring

Novo id de referência, ou "" para limpar.

parent_item_idstring

Novo item pai, ou "" para mover ao primeiro nível.

positioninteger

Nova posição.

open_in_new_tabboolean

Abrir em nova aba.

css_classstring

Classe CSS, ou "" para limpar.

statusstring

ADactivedisabled

D esconde o item da vitrine sem apagá-lo.

200Item atualizado

json

{ "message": "menu item updated" }

Excluir item

DELETE/api/v1/admin/navigation/items/{id}Admin

Exclui um item e seus filhos

Exclusão definitiva. Os subitens do item também são apagados.

Parâmetros de caminho

iduuidobrigatório

Id do item.

200Item excluído

json

{ "message": "menu item deleted" }

Reordenar itens

PUT/api/v1/admin/navigation/menus/{id}/reorderAdmin

Define a posição dos itens pela ordem da lista

Atribui position 0, 1, 2... aos ids na ordem em que você os envia, numa única transação. Itens que não estão na lista não são alterados. Ids que não pertencem ao menu são ignorados em silêncio.

Parâmetros de caminho

iduuidobrigatório

Id do menu.

Corpo da requisição

item_idsarrayobrigatório

Ids dos itens na ordem desejada. Não pode ser vazio.

200Itens reordenados

json

{ "message": "menu items reordered" }

Erros

Status	Quando	Corpo
400	Corpo inválido; `label` ou `item_type` ausente (criar); `item_ids` vazio (reordenar)	`{"error":"label is required"}`, `{"error":"item_type is required"}` ou `{"error":"item_ids is required"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_layouts`	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Item inexistente (alterar, excluir)	`{"error":"menu item not found"}`
500	`label` em branco, tipo inválido, `url` mal formada, referência inexistente, ciclo ou profundidade acima de 5 (criar/alterar); menu inexistente em criar ou reordenar; `id` que não é UUID	`{"error":"failed to create menu item","detail":"invalid URL format: must start with /, http://, or https://"}`

Veja também

Itens do menu

Cria, altera, exclui e reordena os itens (links) de um menu de navegação.

Os itens são os links do menu. Eles formam uma árvore: um item pode ter filhos (um submenu), até 5 níveis. Todas as rotas exigem o privilégio manage_layouts.

Criar item

POST/api/v1/admin/navigation/menus/{id}/itemsAdmin

Adiciona um item a um menu

Parâmetros de caminho

iduuidobrigatório

Id do menu.

Corpo da requisição

labelstringobrigatório

Texto do link. Não pode ser vazio nem só espaços.

item_typestringobrigatório

categorypageproductcustom_link

Tipo do item.

reference_iduuid

Id da categoria, produto ou página. Obrigatório nos três tipos de referência.

urlstring

Endereço do link. Obrigatório em custom_link.

parent_item_iduuid

Item pai, para criar um submenu. Respeita o limite de 5 níveis e não permite ciclo.

positionintegerpadrão: fim

Ordem entre os irmãos, a partir de 0. Com 0 ou omitido vai para o fim.

open_in_new_tabbooleanpadrão: false

Abrir em nova aba.

css_classstring

Classe CSS extra.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/navigation/menus/$MENU_ID/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Fale conosco","item_type":"custom_link","url":"/contato"}'

201Item criado

json

{
  "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "menu_id": "b4d75fb9-9e16-4efa-b15d-5b5547af37fb",
  "label": "Fale conosco",
  "url": "/contato",
  "item_type": "custom_link",
  "position": 5,
  "open_in_new_tab": false,
  "status": "A",
  "created_at": "2026-10-11T18:10:00.000Z",
  "updated_at": "2026-10-11T18:10:00.000Z"
}

Alterar item

PUT/api/v1/admin/navigation/items/{id}Admin

Altera um item do menu

Parâmetros de caminho

iduuidobrigatório

Id do item.

Corpo da requisição

labelstring

Novo texto.

urlstring

Novo endereço.

item_typestring

categorypageproductcustom_link

Novo tipo.

reference_idstring

Novo id de referência, ou "" para limpar.

parent_item_idstring

Novo item pai, ou "" para mover ao primeiro nível.

positioninteger

Nova posição.

open_in_new_tabboolean

Abrir em nova aba.

css_classstring

Classe CSS, ou "" para limpar.

statusstring

ADactivedisabled

D esconde o item da vitrine sem apagá-lo.

200Item atualizado

json

{ "message": "menu item updated" }

Excluir item

DELETE/api/v1/admin/navigation/items/{id}Admin

Exclui um item e seus filhos

Exclusão definitiva. Os subitens do item também são apagados.

Parâmetros de caminho

iduuidobrigatório

Id do item.

200Item excluído

json

{ "message": "menu item deleted" }

Reordenar itens

PUT/api/v1/admin/navigation/menus/{id}/reorderAdmin

Define a posição dos itens pela ordem da lista

Parâmetros de caminho

iduuidobrigatório

Id do menu.

Corpo da requisição

item_idsarrayobrigatório

Ids dos itens na ordem desejada. Não pode ser vazio.

200Itens reordenados

json

{ "message": "menu items reordered" }

Erros

Status	Quando	Corpo
400	Corpo inválido; `label` ou `item_type` ausente (criar); `item_ids` vazio (reordenar)	`{"error":"label is required"}`, `{"error":"item_type is required"}` ou `{"error":"item_ids is required"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_layouts`	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Item inexistente (alterar, excluir)	`{"error":"menu item not found"}`
500	`label` em branco, tipo inválido, `url` mal formada, referência inexistente, ciclo ou profundidade acima de 5 (criar/alterar); menu inexistente em criar ou reordenar; `id` que não é UUID	`{"error":"failed to create menu item","detail":"invalid URL format: must start with /, http://, or https://"}`