Layouts simples

Um layout define quais blocos aparecem numa página da vitrine (logo, busca, vitrine de produtos, texto, rodapé...) e em que zona. Esta seção documenta o layout simples: um registro com uma lista plana de blocos guardada como JSON, criado para um tipo de página (homepage, product, category, vendor ou custom). É o modelo mais antigo da plataforma.

Como funciona

1. Crie o layout
   POST /api/v1/admin/layouts com name e, se quiser, page_type e a lista inicial de blocks.
2. Monte os blocos
   Adicione, edite, remova e reordene blocos pelas rotas de blocos, ou substitua a lista inteira com PUT /api/v1/admin/layouts/{id}.
3. Marque como padrão
   Use definir padrão para que seja o layout do tipo de página.

Conceitos-chave

Tipos de página

Blocos e zonas

Um bloco tem type (o que ele é: logo, search_bar, text_html, recent_products, hero_banner...), position (a zona: header, main_top, main, main_bottom, sidebar_left, sidebar_right ou footer), order (a ordem dentro da zona, a partir de 0), title, config (objeto livre com as opções do bloco) e visible. As ordens são renumeradas em sequência 0, 1, 2 dentro de cada zona sempre que você remove ou reordena blocos.

Layout avançado: onde estão os blocos de verdade

Se você chamar uma destas rotas de bloco com o id de um layout avançado (o id da tela /admin/layouts/{id}/edit do painel), recebe 404 com a explicação e a rota equivalente do layout avançado.

Endpoints

Erros comuns

• Achar que mudar o layout simples muda a loja. Não muda: veja o aviso acima.
• Usar o id do editor visual (ou de um layout avançado) aqui. Retorna 404 em consultar e nas rotas de bloco; em alterar, excluir, duplicar e definir padrão o erro vem como 500.
• Enviar blocks no PUT achando que é parcial. O campo blocks substitui a lista inteira.
• PUT sem nenhum campo. Retorna 500 no fields to update.
• Mandar id não numérico. Retorna 400 invalid layout id.
• Esperar lista vazia como []. Quando nada atende ao filtro a lista vem como "layouts": null.

Próximos passos