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

Rascunho do tema

Guarda um rascunho do tema, publica-o aplicando tudo de uma vez ou o descarta.

O rascunho permite montar uma alteração grande no seu cliente (por exemplo, um editor visual) e aplicá-la de uma só vez. Há um rascunho por tema: salvar de novo substitui o anterior. O conteúdo é um JSON livre (draft_data), mas só as chaves abaixo são aplicadas na publicação.

O que a publicação aplica

global_settings_values (substitui os ajustes globais do tema); templates[] com id e sections[] (para cada modelo listado, apaga todas as seções atuais e recria a partir da lista, com seus blocks[]); header_group e footer_group com id e sections[] (mesma regra). Cada seção usa section_definition_id, name, settings_values, visible (padrão true), custom_css e blocks[] com block_type, name, settings_values, visible. Depois de aplicar, o rascunho é apagado.

Obter rascunho

Devolve o rascunho salvo, ou draft: null quando não há.

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

Obter o rascunho 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/draft" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rascunho
json
{
  "draft": {
    "id": "d1d1d1d1-0000-4000-8000-000000000001",
    "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
    "draft_data": {
      "global_settings_values": {
        "primary_color": "#B45309"
      },
      "templates": [
        {
          "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
          "sections": [
            {
              "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
              "name": "rich-text",
              "settings_values": {
                "heading": "Novidades"
              },
              "visible": true,
              "blocks": []
            }
          ]
        }
      ]
    },
    "created_by": "",
    "created_at": "2026-10-11T12:00:00Z",
    "updated_at": "2026-10-11T12:00:00Z"
  }
}
200Sem rascunho
json
{
  "draft": null
}

Campos da resposta

draftobject

O rascunho ou null.

iduuid
Id do rascunho.
theme_iduuid
Tema do rascunho.
draft_dataobject
O conteúdo salvo, como foi enviado.
created_bystring
Quem salvou, como enviado.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id do caminho não é um UUID.{"error":"invalid id","detail":"id must be a valid UUID"}
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 get draft","detail":"..."}

Salvar rascunho

Grava o rascunho, substituindo o existente. Nada muda na vitrine até a publicação.

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

Salvar o rascunho do tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Corpo da requisição

draft_dataobjectobrigatório
Conteúdo do rascunho (veja as chaves aplicadas acima). Obrigatório.
created_bystring
Texto livre que identifica quem salvou.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/draft" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "draft_data": {
      "global_settings_values": {
        "primary_color": "#B45309"
      },
      "templates": [
        {
          "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
          "sections": [
            {
              "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
              "name": "rich-text",
              "settings_values": {
                "heading": "Novidades"
              },
              "visible": true,
              "blocks": []
            }
          ]
        }
      ]
    },
    "created_by": "editor-visual"
  }'

Resposta

200Rascunho salvo
json
{
  "id": "d1d1d1d1-0000-4000-8000-000000000001",
  "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "draft_data": {
    "global_settings_values": {
      "primary_color": "#B45309"
    },
    "templates": [
      {
        "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
        "sections": [
          {
            "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
            "name": "rich-text",
            "settings_values": {
              "heading": "Novidades"
            },
            "visible": true,
            "blocks": []
          }
        ]
      }
    ]
  },
  "created_by": "",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid
Id do rascunho.
theme_iduuid
Tema do rascunho.
draft_dataobject
O conteúdo salvo, como foi enviado.
created_bystring
Quem salvou, como enviado.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id do caminho não é um UUID.{"error":"invalid id","detail":"id must be a valid UUID"}
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400draft_data ausente ou nulo.{"error":"draft_data is 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"}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to save draft","detail":"..."}

Publicar rascunho

Aplica o rascunho ao tema em uma transação e apaga o rascunho. A verificação de orçamento de desempenho (imagens e scripts) roda antes, como em publicar o tema, com os mesmos parâmetros force e optimize. Devolve o tema atualizado. Sem corpo.

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

Aplicar o rascunho ao tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Parâmetros de consulta

forceboolean
true ignora o orçamento de desempenho.
optimizeboolean
true otimiza as imagens que estouram o limite antes de aplicar.

Exemplo de requisição

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

Resposta

200Rascunho aplicado
json
{
  "id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "name": "Default",
  "slug": "default",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "version": "1.0.0",
  "status": "A",
  "is_live": true,
  "global_settings_schema": [
    {
      "key": "primary_color",
      "type": "color",
      "label": "Primary Color",
      "default": "#2563EB"
    }
  ],
  "global_settings_values": {
    "primary_color": "#2563EB",
    "font_body": "Inter",
    "border_radius": 8
  },
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}
422Orçamento de desempenho estourado
json
{
  "violations": [
    {
      "rule": "image_size",
      "severity": "error",
      "asset_url": "/uploads/banner.png",
      "actual_bytes": 4200000,
      "limit_bytes": 400000,
      "fix": "auto"
    }
  ]
}

Campos da resposta

iduuid
Id do tema.
namestring
Nome.
slugstring
Identificador curto, único na loja.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão do tema, texto livre (1.0.0).
statusstring
Estado em letra: R rascunho, A publicado, L ao vivo, D arquivado. Tema "ao vivo" é indicado por is_live.
is_liveboolean
true no tema que a vitrine está usando. Só um por loja.
global_settings_schemaobject[]
Definição dos ajustes globais do tema (cores, fontes...): cada item tem key, type, label, default e, conforme o tipo, options, min, max, step, unit, placeholder, info. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product.
global_settings_valuesobject
Valores atuais dos ajustes globais, por key.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id do caminho não é um UUID.{"error":"invalid id","detail":"id must be a valid UUID"}
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"}
404O tema não tem rascunho.{"error":"no draft found for this theme","detail":"not found: no draft for theme ..."}
422Violações de orçamento de desempenho com severidade error.{"violations":[...]}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to publish draft","detail":"..."}
Seções são recriadas

Como as seções dos modelos listados são apagadas e recriadas, os ids das seções e dos blocos mudam a cada publicação. Não guarde esses ids em outros sistemas.

Descartar rascunho

Apaga o rascunho sem aplicar nada.

DELETE/api/v1/admin/theme-builder/themes/{id}/draftAdmin

Descartar o rascunho

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Exemplo de requisição

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

Resposta

200Descartado
json
{
  "message": "draft discarded"
}

Erros

StatusQuandoCorpo de exemplo
400O id do caminho não é um UUID.{"error":"invalid id","detail":"id must be a valid UUID"}
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"}
404O tema não tem rascunho.{"error":"no draft found for this theme","detail":"not found: no draft for theme ..."}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to discard draft","detail":"..."}

Veja também

  • Theme Builder: visão geral
  • Ciclo de vida do tema
Anterior
Importar e exportar tema
Próxima
Definições de seção
Nesta página
  • Obter rascunho
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar rascunho
  • Exemplo de requisição
  • Resposta
  • Erros
  • Publicar rascunho
  • Exemplo de requisição
  • Resposta
  • Erros
  • Descartar rascunho
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também