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

Resposta

200Rascunho
200Sem rascunho

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

Resposta

200Rascunho salvo

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

Resposta

200Rascunho aplicado
422Orçamento de desempenho estourado

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

Resposta

200Descartado

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
bash
curl -X GET "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/draft" \
  -H "Authorization: Bearer $TOKEN"
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"
  }'
bash
curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/draft/publish" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X DELETE "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/draft" \
  -H "Authorization: Bearer $TOKEN"
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"
  }
}
json
{
  "draft": null
}
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"
}
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"
}
json
{
  "violations": [
    {
      "rule": "image_size",
      "severity": "error",
      "asset_url": "/uploads/banner.png",
      "actual_bytes": 4200000,
      "limit_bytes": 400000,
      "fix": "auto"
    }
  ]
}
json
{
  "message": "draft discarded"
}