VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Theme Builder

Modelos de página

Lista, consulta, cria e altera os modelos de página do tema e substitui todas as suas seções de uma vez.

Um modelo (template) descreve uma tela do tema, como a home ou a página de produto, e é identificado por um page_type. Cada tema tem no máximo um modelo por page_type. O conteúdo do modelo é a lista ordenada de seções. Cabeçalho e rodapé não ficam no modelo: são grupos compartilhados por todas as páginas.

Listar modelos

Devolve os modelos do tema, sem as seções.

GET/api/v1/admin/theme-builder/themes/{id}/templatesAdmin

Listar os modelos do tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/templates" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelos
json
{
  "templates": [
    {
      "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
      "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
      "page_type": "index",
      "name": "Homepage",
      "seo_title": "Bem-vindo à Nossa Loja",
      "seo_description": "Descubra produtos incríveis com ótimos preços.",
      "created_at": "2026-04-07T02:46:02.491306Z",
      "updated_at": "2026-04-07T02:46:02.491306Z"
    }
  ]
}

Campos da resposta

templatesarray

Modelos.

iduuid
Id do modelo.
theme_iduuid
Tema dono.
page_typestring
Tipo de página, único por tema. Exemplos: index, product, collection, cart, blog, page, 404, search, vendor.
namestring
Nome.
seo_titlestring
Título SEO.
seo_descriptionstring
Meta description.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500O id do caminho não é um UUID. Esta rota não valida antes e devolve 500 com a mensagem do banco em português.{"error":"failed to list templates","detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to list templates","detail":"..."}

Obter modelo

Devolve o modelo. As seções vêm de listar seções.

GET/api/v1/admin/theme-builder/templates/{id}Admin

Obter um modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do modelo.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/theme-builder/templates/30a0a88f-2eba-4a7a-bdea-ab73b761ab99" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelo
json
{
  "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
  "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "page_type": "index",
  "name": "Homepage",
  "seo_title": "Bem-vindo à Nossa Loja",
  "seo_description": "Descubra produtos incríveis com ótimos preços.",
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id do modelo.
theme_iduuid
Tema dono.
page_typestring
Tipo de página, único por tema. Exemplos: index, product, collection, cart, blog, page, 404, search, vendor.
namestring
Nome.
seo_titlestring
Título SEO.
seo_descriptionstring
Meta description.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
404Modelo não existe.{"error":"template not found"}
500O id do caminho não é um UUID. Esta rota não valida antes e devolve 500 com a mensagem do banco em português.{"error":"failed to get template","detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}

Criar modelo

Cria um modelo vazio para um tipo de página.

POST/api/v1/admin/theme-builder/themes/{id}/templatesAdmin

Criar um modelo de página

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Corpo da requisição

page_typestringobrigatório
Tipo de página. Único por tema.
namestringobrigatório
Nome.
seo_titlestring
Título SEO.
seo_descriptionstring
Meta description.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page_type": "cart",
    "name": "Carrinho",
    "seo_title": "Seu carrinho"
  }'

Resposta

201Modelo criado
json
{
  "id": "e4e4e4e4-0000-4000-8000-000000000004",
  "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "page_type": "cart",
  "name": "Carrinho",
  "seo_title": "Seu carrinho",
  "seo_description": "",
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id do modelo.
theme_iduuid
Tema dono.
page_typestring
Tipo de página, único por tema. Exemplos: index, product, collection, cart, blog, page, 404, search, vendor.
namestring
Nome.
seo_titlestring
Título SEO.
seo_descriptionstring
Meta description.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400page_type ou name vazio.{"error":"page_type and name are required"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500Já existe modelo com esse page_type no tema, ou tema inexistente.{"error":"failed to create template","detail":"..."}

Atualizar modelo

Altera nome e campos de SEO. O page_type não pode ser alterado.

PUT/api/v1/admin/theme-builder/templates/{id}Admin

Atualizar nome e SEO do modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do modelo.

Corpo da requisição

namestring
Nome.
seo_titlestring
Título SEO.
seo_descriptionstring
Meta description.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/templates/30a0a88f-2eba-4a7a-bdea-ab73b761ab99" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seo_title": "Minha Loja | Ofertas"
  }'

Resposta

200Modelo atualizado
json
{
  "message": "template updated"
}

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
404Modelo não existe.{"error":"template not found","detail":"not found: ..."}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to update template","detail":"..."}

Salvar todas as seções

Apaga todas as seções atuais do modelo (e os blocos delas) e cria as da lista, na ordem do array, em uma transação. Serve para salvar a tela inteira de uma vez.

PUT/api/v1/admin/theme-builder/templates/{id}/sectionsAdmin

Substituir todas as seções do modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do modelo.

Corpo da requisição

sectionsobject[]obrigatório

Seções, na ordem final.

section_definition_iduuidobrigatório
Definição da seção.
namestring
Nome da instância.
settings_valuesobjectpadrão: {}
Valores dos campos da definição, por key.
sort_orderinteger
Ignorado: a ordem é a do array.
custom_cssstring
CSS livre da seção.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/templates/30a0a88f-2eba-4a7a-bdea-ab73b761ab99/sections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sections": [
      {
        "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
        "name": "Novidades",
        "settings_values": {
          "heading": "Novidades da semana"
        }
      }
    ]
  }'

Resposta

200Seções salvas
json
{
  "message": "sections saved"
}

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to bulk save sections","detail":"..."}
Blocos são perdidos

Esta rota recria só as seções, sem os blocos, e os ids mudam. Todo bloco que existia nas seções antigas é apagado. Se as seções têm blocos, use publicar rascunho, que recria também os blocos, ou as rotas de seções e blocos.

Veja também

  • Theme Builder: visão geral
  • Seções
Anterior
Definições de seção
Próxima
Grupos de cabeçalho e rodapé
Nesta página
  • Listar modelos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Obter modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar todas as seções
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também