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

Modelos de tema

Lista, consulta, aplica, exclui e semeia os modelos de tema prontos do AI Builder.

Um modelo é uma proposta de tema salva (cores, fontes, ajustes, e o que mais a IA tenha proposto) que pode ser aplicada sem nova conversa. Há modelos de fábrica (como "Elegant Fashion" e "Modern Minimal"), criados por semeadura, e os que o administrador salvou de uma sessão.

Listar modelos

Devolve todos os modelos da loja, públicos ou não, do mais novo ao mais antigo.

GET/api/v1/admin/ai-builder/templatesAdmin

Listar todos os modelos

Requer o privilégio manage_theme.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/ai-builder/templates" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelos
json
{
  "templates": [
    {
      "id": "01f6a13e-841c-483b-b228-ca8df1200b5f",
      "name": "Elegant Fashion",
      "description": "Refined cream and charcoal palette with Cormorant Garamond headings and Lato body text.",
      "category": "fashion",
      "tags": [
        "fashion",
        "elegant"
      ],
      "thumbnail_url": "",
      "output_json": {
        "theme": {
          "primary_color": "#1c1917",
          "font_family": "Lato",
          "heading_font": "Cormorant Garamond"
        }
      },
      "is_public": true,
      "created_by": "",
      "created_at": "2026-07-01T10:00:00Z"
    }
  ]
}

Campos da resposta

templatesarray

Modelos.

iduuid
Id do modelo.
namestring
Nome.
descriptionstring
Descrição.
categorystring
Categoria.
tagsstring[]
Etiquetas.
thumbnail_urlstring
Miniatura.
output_jsonobject
A proposta salva (mesmo formato de current_output da sessão).
is_publicboolean
Aparece na lista pública.
created_bystring
Quem criou. Vazio nos modelos de fábrica.
created_atstring
Criaçã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"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to list templates","detail":"..."}

Listar modelos públicos

Devolve só os modelos com is_public: true. Apesar do nome, a rota exige o mesmo token de administrador das demais.

GET/api/v1/admin/ai-builder/templates/publicAdmin

Listar só os modelos públicos

Requer o privilégio manage_theme.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/ai-builder/templates/public" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelos públicos
json
{
  "templates": [
    {
      "id": "01f6a13e-841c-483b-b228-ca8df1200b5f",
      "name": "Elegant Fashion",
      "description": "Refined cream and charcoal palette with Cormorant Garamond headings and Lato body text.",
      "category": "fashion",
      "tags": [
        "fashion",
        "elegant"
      ],
      "thumbnail_url": "",
      "output_json": {
        "theme": {
          "primary_color": "#1c1917",
          "font_family": "Lato",
          "heading_font": "Cormorant Garamond"
        }
      },
      "is_public": true,
      "created_by": "",
      "created_at": "2026-07-01T10:00:00Z"
    }
  ]
}

Campos da resposta

templatesarray

Modelos públicos.

iduuid
Id do modelo.
namestring
Nome.
descriptionstring
Descrição.
categorystring
Categoria.
tagsstring[]
Etiquetas.
thumbnail_urlstring
Miniatura.
output_jsonobject
A proposta salva (mesmo formato de current_output da sessão).
is_publicboolean
Aparece na lista pública.
created_bystring
Quem criou. Vazio nos modelos de fábrica.
created_atstring
Criaçã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"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to list public templates","detail":"..."}

Obter modelo

Devolve o modelo com a proposta completa em output_json.

GET/api/v1/admin/ai-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/ai-builder/templates/01f6a13e-841c-483b-b228-ca8df1200b5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Modelo
json
{
  "id": "01f6a13e-841c-483b-b228-ca8df1200b5f",
  "name": "Elegant Fashion",
  "description": "Refined cream and charcoal palette with Cormorant Garamond headings and Lato body text.",
  "category": "fashion",
  "tags": [
    "fashion",
    "elegant"
  ],
  "thumbnail_url": "",
  "output_json": {
    "theme": {
      "primary_color": "#1c1917",
      "font_family": "Lato",
      "heading_font": "Cormorant Garamond"
    }
  },
  "is_public": true,
  "created_by": "",
  "created_at": "2026-07-01T10:00:00Z"
}

Campos da resposta

iduuid
Id do modelo.
namestring
Nome.
descriptionstring
Descrição.
categorystring
Categoria.
tagsstring[]
Etiquetas.
thumbnail_urlstring
Miniatura.
output_jsonobject
A proposta salva (mesmo formato de current_output da sessão).
is_publicboolean
Aparece na lista pública.
created_bystring
Quem criou. Vazio nos modelos de fábrica.
created_atstring
Criaçã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. A rota não valida antes: 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."}

Excluir modelo

Remove o modelo. Quem já o aplicou não é afetado.

DELETE/api/v1/admin/ai-builder/templates/{id}Admin

Excluir um modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do modelo.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/ai-builder/templates/01f6a13e-841c-483b-b228-ca8df1200b5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído
json
{
  "status": "deleted"
}

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. A rota não valida antes: devolve 500 com a mensagem do banco, em português.{"error":"failed to delete 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."}

Aplicar modelo

Aplica a proposta do modelo à loja, com os mesmos efeitos de aplicar uma sessão, mas sem guardar retrato do tema anterior: não há como desfazer. Sem corpo.

POST/api/v1/admin/ai-builder/templates/{id}/applyAdmin

Aplicar um modelo à loja

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do modelo.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-builder/templates/01f6a13e-841c-483b-b228-ca8df1200b5f/apply" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aplicado
json
{
  "status": "applied"
}

Erros

StatusQuandoCorpo de exemplo
400O modelo não tem proposta (template has no output to apply).{"error":"template has no output to apply"}
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"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to apply template","detail":"..."}
Sem desfazer

Antes de aplicar um modelo numa loja em produção, anote os valores do tema atual (exporte o tema) para poder restaurá-los à mão.

Semear modelos de fábrica

Insere os modelos de fábrica que ainda não existem e informa quantos foram inseridos. Pode ser repetido sem criar duplicatas. Sem corpo.

POST/api/v1/admin/ai-builder/templates/seedAdmin

Criar os modelos de fábrica

Requer o privilégio manage_theme.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-builder/templates/seed" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Semeado
json
{
  "status": "seeded",
  "inserted": 0
}

Campos da resposta

statusstring
Sempre seeded.
insertedinteger
Quantos modelos novos foram inseridos.

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"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to seed templates","detail":"..."}

Veja também

  • AI Builder: visão geral
  • Aplicar e desfazer
Anterior
Arquivos e análise de referência
Próxima
Ajustes do AI Builder
Nesta página
  • Listar modelos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar modelos públicos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Obter modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Aplicar modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Semear modelos de fábrica
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também