Layouts avançados

Os layouts avançados são o desenho da vitrine: cada tela da loja (home, produto, carrinho...) é uma árvore de contêineres, linhas, colunas e blocos que o administrador monta e reorganiza sem programar. Esta área é a API por trás do editor visual "Edit Design".

Como funciona

Um layout tem várias páginas (uma por tela, identificada por um dispatch). Cada página tem quatro contêineres, que são as faixas verticais da tela. Dentro deles ficam as linhas, depois as colunas (grade de 12) e, por fim, os blocos.

Fluxo típico de integração:

1. Abra um rascunho
   POST /advanced-layouts/draft devolve o draft_id, uma cópia do layout no ar.
2. Leia e edite
   GET /advanced-layouts/{id} com o draft_id; crie, altere, mova e exclua linhas, colunas e blocos.
3. Confira
   Abra a vitrine com ?layout_id=<draft_id> para ver o rascunho sem publicar.
4. Publique
   POST /advanced-layouts/{draft_id}/publish, para uma página (dispatch) ou para o rascunho inteiro.

Conceitos-chave

Dispatch

O dispatch é o código da tela, no formato area.acao: index.index (home), products.view (produto), categories.view (categoria), checkout.cart (carrinho), auth.login, blog.view, vendors.profile, search.view e outros. Além deles existe a página "Default (Catch-all)" e, na Loja WhatsApp, os dispatches wa.*.

Configuração, conteúdo e design

config guarda as opções do tipo de bloco (chaves listadas no catálogo). content é um espaço livre. design é a camada de estilo universal (fundo, espaçamento, borda, sombra, tipografia...), com sobrescritas para tablet e mobile. custom_css e custom_class permitem estilo livre; <script> e @import são removidos.

Visibilidade

Linhas, colunas e blocos têm visibility por dispositivo (desktop, tablet, mobile) e usergroup_ids para restringir a grupos de compradores (guest, registered ou UUIDs). A vitrine pública filtra pelos grupos do visitante; estas rotas de administração mostram tudo.

Status do bloco

O status é uma letra: A (ativo) ou D (inativo). Ao gravar você pode mandar active/inactive, mas a resposta sempre traz a letra.

Patches e bloqueio 409

Um bloco criado ou ajustado por um patch aplicado na loja fica protegido: alterar, mover ou excluir devolve 409 com code: patch_owned.

Histórico

Quase toda escrita fica registrada com autor, ação e detalhes. Leia em Consultar layouts.

Endpoints

Erros comuns

• Editar o layout publicado diretamente. Qualquer clique já vale para os clientes; use o rascunho.
• Enviar config parcial em PUT /blocks/{id} achando que será mesclado. O objeto é substituído: leia, altere e devolva completo.
• Usar o id do layout publicado nas rotas de edição depois de abrir o rascunho. Os blocos do rascunho têm ids diferentes.
• Tentar excluir o layout padrão. Devolve 409: promova outro antes.
• Esperar 404 para ids que não existem em todas as rotas. Várias escritas (atualizar página, linha, coluna, bloco) devolvem 500 para ids inexistentes.
• Criar um segundo main_content na mesma página. Só um é permitido.
• Mandar um id que não é inteiro. Devolve 400 com id must be an integer.

Próximos passos