API atual/Referência completa/Temas da vitrine

Temas

Lista, consulta, cria, altera e exclui temas da vitrine.

Cadastro básico dos temas da loja. Todas as rotas exigem o privilégio manage_theme. Para trocar o tema em uso, veja Ativar, copiar e importar.

Listar temas

GET/api/v1/admin/storefront-themesAdmin

Lista todos os temas da loja

Devolve todos os temas, sem paginação, com a contagem de estilos de cada um (sem os estilos em si).

200Temas retornados

json

{
  "themes": [
    {
      "id": "a650691c-22f3-4508-9a83-9418c04976a6",
      "name": "Default",
      "slug": "default",
      "is_active": true,
      "position": 0,
      "thumbnail_url": "",
      "created_at": "2026-07-10T07:22:15.042557Z",
      "updated_at": "2026-07-27T14:32:28.637278Z",
      "style_count": 214
    }
  ],
  "total": 15
}

Campos da resposta

themes[].iduuid

Identificador do tema.

themes[].namestring

Nome.

themes[].slugstring

Código gerado do nome na criação. Não muda ao renomear.

themes[].is_activeboolean

Se é o tema em uso. Só um é true.

themes[].positioninteger

Ordem de exibição na galeria. Pode repetir entre temas.

themes[].thumbnail_urlstring

URL da miniatura. Pode ser vazia.

themes[].style_countinteger

Quantidade de estilos. Só vem preenchido na listagem.

themes[].created_atstring

Criação (RFC 3339, UTC).

themes[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Quantidade de temas.

Consultar tema

GET/api/v1/admin/storefront-themes/{id}Admin

Consulta um tema com seus estilos

Devolve o tema com o array styles completo (todas as cores, fontes e CSS de cada estilo). Em temas com muitos estilos a resposta pode ser grande.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

A resposta 200 tem os campos do tema mais styles (descritos em Estilos); style_count fica 0 aqui, use o tamanho do array.

Criar tema

POST/api/v1/admin/storefront-themesAdmin

Cria um tema com um estilo padrão

Cria o tema inativo, com um estilo Default ativo (cores padrão) e um layout inicial Default com a página catch-all e um bloco de conteúdo principal, para que ele já renderize ao ser ativado. O slug é gerado do nome. A posição é a seguinte à maior existente.

Corpo da requisição

namestringpadrão: Untitled Theme

Nome do tema.

thumbnail_urlstring

URL da miniatura.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Natal 2026"}'

201Tema criado

json

{
  "id": "3c2f1a60-9d1e-4b5a-8c3e-7f4a1b2c3d4e",
  "name": "Natal 2026",
  "slug": "natal-2026",
  "is_active": false,
  "position": 101,
  "thumbnail_url": "",
  "created_at": "2026-10-11T16:00:00.000Z",
  "updated_at": "2026-10-11T16:00:00.000Z",
  "style_count": 0,
  "styles": [
    { "id": "e0c1d2f3-1111-4222-8333-444455556666", "name": "Default", "is_active": true, "primary_color": "#2563eb" }
  ]
}

Os campos do estilo foram abreviados no exemplo.

Alterar tema

PUT/api/v1/admin/storefront-themes/{id}Admin

Altera nome, miniatura ou posição de um tema

Alteração parcial. Não troca o slug. Só mexe nos metadados; cores e fontes ficam nos estilos.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

Corpo da requisição

namestring

Novo nome.

thumbnail_urlstring

Nova miniatura.

positioninteger

Nova posição.

A resposta 200 é o tema atualizado.

Excluir tema

DELETE/api/v1/admin/storefront-themes/{id}Admin

Exclui um tema inativo com seus estilos e layouts

Exclusão definitiva, em cascata: os estilos e os layouts do tema também são apagados. O tema ativo não pode ser excluído.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema excluído

json

{ "message": "deleted" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema inexistente	`{"error":"not found","detail":"not found"}`
409	Excluir o tema ativo	`{"error":"cannot delete active theme","detail":"cannot delete the active theme"}`
500	`id` que não é UUID, ou falha interna	`{"error":"failed to get theme","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

API atual/Referência completa/Temas da vitrine

Temas

Lista, consulta, cria, altera e exclui temas da vitrine.

Cadastro básico dos temas da loja. Todas as rotas exigem o privilégio manage_theme. Para trocar o tema em uso, veja Ativar, copiar e importar.

Listar temas

GET/api/v1/admin/storefront-themesAdmin

Lista todos os temas da loja

Devolve todos os temas, sem paginação, com a contagem de estilos de cada um (sem os estilos em si).

200Temas retornados

json

{
  "themes": [
    {
      "id": "a650691c-22f3-4508-9a83-9418c04976a6",
      "name": "Default",
      "slug": "default",
      "is_active": true,
      "position": 0,
      "thumbnail_url": "",
      "created_at": "2026-07-10T07:22:15.042557Z",
      "updated_at": "2026-07-27T14:32:28.637278Z",
      "style_count": 214
    }
  ],
  "total": 15
}

Campos da resposta

themes[].iduuid

Identificador do tema.

themes[].namestring

Nome.

themes[].slugstring

Código gerado do nome na criação. Não muda ao renomear.

themes[].is_activeboolean

Se é o tema em uso. Só um é true.

themes[].positioninteger

Ordem de exibição na galeria. Pode repetir entre temas.

themes[].thumbnail_urlstring

URL da miniatura. Pode ser vazia.

themes[].style_countinteger

Quantidade de estilos. Só vem preenchido na listagem.

themes[].created_atstring

Criação (RFC 3339, UTC).

themes[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Quantidade de temas.

Consultar tema

GET/api/v1/admin/storefront-themes/{id}Admin

Consulta um tema com seus estilos

Devolve o tema com o array styles completo (todas as cores, fontes e CSS de cada estilo). Em temas com muitos estilos a resposta pode ser grande.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

A resposta 200 tem os campos do tema mais styles (descritos em Estilos); style_count fica 0 aqui, use o tamanho do array.

Criar tema

POST/api/v1/admin/storefront-themesAdmin

Cria um tema com um estilo padrão

Corpo da requisição

namestringpadrão: Untitled Theme

Nome do tema.

thumbnail_urlstring

URL da miniatura.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Natal 2026"}'

201Tema criado

json

{
  "id": "3c2f1a60-9d1e-4b5a-8c3e-7f4a1b2c3d4e",
  "name": "Natal 2026",
  "slug": "natal-2026",
  "is_active": false,
  "position": 101,
  "thumbnail_url": "",
  "created_at": "2026-10-11T16:00:00.000Z",
  "updated_at": "2026-10-11T16:00:00.000Z",
  "style_count": 0,
  "styles": [
    { "id": "e0c1d2f3-1111-4222-8333-444455556666", "name": "Default", "is_active": true, "primary_color": "#2563eb" }
  ]
}

Os campos do estilo foram abreviados no exemplo.

Alterar tema

PUT/api/v1/admin/storefront-themes/{id}Admin

Altera nome, miniatura ou posição de um tema

Alteração parcial. Não troca o slug. Só mexe nos metadados; cores e fontes ficam nos estilos.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

Corpo da requisição

namestring

Novo nome.

thumbnail_urlstring

Nova miniatura.

positioninteger

Nova posição.

A resposta 200 é o tema atualizado.

Excluir tema

DELETE/api/v1/admin/storefront-themes/{id}Admin

Exclui um tema inativo com seus estilos e layouts

Exclusão definitiva, em cascata: os estilos e os layouts do tema também são apagados. O tema ativo não pode ser excluído.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema excluído

json

{ "message": "deleted" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema inexistente	`{"error":"not found","detail":"not found"}`
409	Excluir o tema ativo	`{"error":"cannot delete active theme","detail":"cannot delete the active theme"}`
500	`id` que não é UUID, ou falha interna	`{"error":"failed to get theme","detail":"o valor \"abc\" não é um uuid válido. ..."}`