API atual/Referência completa/Theme Builder

Importar e exportar tema

Exporta um tema inteiro como JSON e importa esse JSON como um tema novo em rascunho.

Use para levar um tema de uma loja para outra, guardar uma cópia de segurança ou versionar a aparência fora da plataforma. A exportação traz tudo: dados do tema, definições de seção, modelos (com suas seções e blocos) e grupos de cabeçalho e rodapé. A importação lê o mesmo formato.

Exportar tema

Devolve o tema completo em um único objeto JSON, pronto para ser salvo em arquivo e reenviado a importar.

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

Exportar um tema como JSON

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/export" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Tema exportado

json

{
  "exported_at": "2026-10-11T12:00:00Z",
  "theme": {
    "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"
  },
  "section_definitions": [
    {
      "id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
      "slug": "rich-text",
      "name": "Rich Text",
      "category": "content",
      "settings_schema": [
        {
          "key": "heading",
          "type": "text",
          "label": "Heading"
        }
      ]
    }
  ],
  "section_groups": [
    {
      "id": "8464070a-286d-4cfe-9816-c3a3a8282322",
      "group_type": "header",
      "name": "Header",
      "sections": []
    }
  ],
  "templates": [
    {
      "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
      "page_type": "index",
      "name": "Homepage",
      "sections": []
    }
  ]
}

Campos da resposta

exported_atstring

Momento da exportação (RFC 3339).

themeobject

Dados do tema.

section_definitionsobject[]

Definições de seção.

section_groupsobject[]

Grupos header e footer, cada um com suas sections (e os blocks delas).

templatesobject[]

Modelos de página, cada um com sections (e blocks).

Erros

Status	Quando	Corpo de exemplo
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema não existe.	`{"error":"theme not found","detail":"not found: theme ..."}`
500	O 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 export theme","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."}`

Importar tema

Cria um tema novo a partir do JSON exportado. O nome ganha o sufixo (Imported), o slug vira <slug>-imported-<timestamp>, o estado é rascunho e o tema não vai ao vivo. Todos os ids são gerados de novo; o JSON original não precisa e não reaproveita ids.

POST/api/v1/admin/theme-builder/themes/importAdmin

Importar um tema exportado

Requer o privilégio manage_theme.

Corpo da requisição

themeobjectobrigatório

Dados do tema (name, slug, description, version, global_settings_schema, global_settings_values...). Obrigatório.

section_definitionsobject[]

Definições de seção.

section_groupsobject[]

Grupos de cabeçalho e rodapé.

templatesobject[]

Modelos de página.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": {
      "name": "Outono 2026",
      "slug": "outono-2026",
      "version": "1.0.0",
      "global_settings_values": {
        "primary_color": "#B45309"
      }
    },
    "section_definitions": [],
    "section_groups": [],
    "templates": []
  }'

Resposta

201Tema importado

json

{
  "id": "b1c2d3e4-2222-4333-8444-555566667777",
  "name": "Outono 2026 (Imported)",
  "slug": "outono-2026-imported-1791800000",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "version": "1.0.0",
  "status": "R",
  "is_live": false,
  "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"
}

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

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid JSON","detail":"..."}`
400	Falta a chave `theme`.	`{"error":"import data missing 'theme' key"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to import theme","detail":"..."}`

Veja também

API atual/Referência completa/Theme Builder

Importar e exportar tema

Exporta um tema inteiro como JSON e importa esse JSON como um tema novo em rascunho.

Exportar tema

Devolve o tema completo em um único objeto JSON, pronto para ser salvo em arquivo e reenviado a importar.

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

Exportar um tema como JSON

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/export" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Tema exportado

json

{
  "exported_at": "2026-10-11T12:00:00Z",
  "theme": {
    "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"
  },
  "section_definitions": [
    {
      "id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
      "slug": "rich-text",
      "name": "Rich Text",
      "category": "content",
      "settings_schema": [
        {
          "key": "heading",
          "type": "text",
          "label": "Heading"
        }
      ]
    }
  ],
  "section_groups": [
    {
      "id": "8464070a-286d-4cfe-9816-c3a3a8282322",
      "group_type": "header",
      "name": "Header",
      "sections": []
    }
  ],
  "templates": [
    {
      "id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
      "page_type": "index",
      "name": "Homepage",
      "sections": []
    }
  ]
}

Campos da resposta

exported_atstring

Momento da exportação (RFC 3339).

themeobject

Dados do tema.

section_definitionsobject[]

Definições de seção.

section_groupsobject[]

Grupos header e footer, cada um com suas sections (e os blocks delas).

templatesobject[]

Modelos de página, cada um com sections (e blocks).

Erros

Status	Quando	Corpo de exemplo
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema não existe.	`{"error":"theme not found","detail":"not found: theme ..."}`
500	O 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 export theme","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."}`

Importar tema

POST/api/v1/admin/theme-builder/themes/importAdmin

Importar um tema exportado

Requer o privilégio manage_theme.

Corpo da requisição

themeobjectobrigatório

Dados do tema (name, slug, description, version, global_settings_schema, global_settings_values...). Obrigatório.

section_definitionsobject[]

Definições de seção.

section_groupsobject[]

Grupos de cabeçalho e rodapé.

templatesobject[]

Modelos de página.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": {
      "name": "Outono 2026",
      "slug": "outono-2026",
      "version": "1.0.0",
      "global_settings_values": {
        "primary_color": "#B45309"
      }
    },
    "section_definitions": [],
    "section_groups": [],
    "templates": []
  }'

Resposta

201Tema importado

json

{
  "id": "b1c2d3e4-2222-4333-8444-555566667777",
  "name": "Outono 2026 (Imported)",
  "slug": "outono-2026-imported-1791800000",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "version": "1.0.0",
  "status": "R",
  "is_live": false,
  "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"
}

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[]

global_settings_valuesobject

Valores atuais dos ajustes globais, por key.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid JSON","detail":"..."}`
400	Falta a chave `theme`.	`{"error":"import data missing 'theme' key"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to import theme","detail":"..."}`