Theme Builder

O Theme Builder monta a vitrine por seções, no estilo de lojas Shopify: o tema reúne ajustes globais (cores, fontes), tipos de seção reutilizáveis, um modelo por tipo de página (home, produto, carrinho...) e os grupos de cabeçalho e rodapé. O lojista escolhe e ordena seções, edita os campos delas e publica. Esta área é a API do editor de temas.

Como funciona

O tema é uma hierarquia: o tema tem definições de seção (os moldes), modelos (um por tipo de página) e grupos (header e footer). Modelos e grupos contêm seções (instâncias de uma definição), e as seções podem ter blocos filhos.

Estados do tema (campo status, uma letra):

Fluxo típico para lançar um tema novo:

1. Parta de algo pronto
   Crie o tema inicial (POST /themes/seed), duplique um tema existente ou importe um JSON exportado.
2. Edite
   Salve alterações como rascunho (POST /themes/{id}/draft) ou use as rotas de seções e blocos diretamente.
3. Aplique
   Publique o rascunho (POST /themes/{id}/draft/publish).
4. Publique o tema
   POST /themes/{id}/publish muda o estado para A.
5. Coloque ao vivo
   POST /themes/{id}/set-live liga o tema à vitrine.

Conceitos-chave

Tipos de campo

Os esquemas (global_settings_schema, settings_schema) descrevem formulários. Cada campo tem key, type, label e default. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product. range e number aceitam min, max, step e unit; select traz options (label e value). O valor preenchido vai em settings_values (ou global_settings_values), indexado pela key.

Orçamento de desempenho

Ao publicar o tema ou o rascunho, o servidor pesa as imagens e scripts do rascunho. Violações de severidade error bloqueiam com 422 e a lista violations. ?force=true ignora; ?optimize=true recomprime as imagens automaticamente. Sem rascunho (ou sem arquivos), nada é bloqueado.

Quem edita o quê

As rotas desta seção são do painel do administrador. A leitura pública da página renderizada pela vitrine é outra rota, fora desta seção.

Erros 500 em vez de 400

Várias rotas não validam o formato do id nem os campos antes de gravar. Um id que não é UUID chega ao banco e volta como 500 com uma mensagem em português; uma violação de unicidade (slug ou page_type repetido) também. Valide no cliente.

Endpoints

Erros comuns

• Chamar set-live num tema que não foi publicado. Devolve 500 com only published themes can be set as live.
• Tentar excluir o tema ao vivo (500, cannot delete the live theme). Coloque outro ao vivo antes.
• Usar PUT /templates/{id}/sections ou PUT /themes/{themeId}/groups/{groupId} com seções que têm blocos. Os blocos são apagados e não recriados.
• Criar uma definição de seção sem slug. O servidor só confere o name e responde 500.
• Guardar ids de seções e blocos em outro sistema: a publicação do rascunho os recria.
• Repetir toggle por retentativa automática: cada chamada inverte a visibilidade.
• Tratar status como texto longo. A resposta traz a letra (A), mesmo que você tenha enviado published.

Próximos passos