API atual/Referência completa/AI Builder

Aplicar e desfazer

Visualiza a proposta, aplica a sessão à loja, desfaz o tema aplicado e salva a proposta como modelo.

Até aqui a proposta só existe dentro da sessão. Aplicar grava na loja de verdade. Antes disso, visualize; depois, se não gostou, desfaça o tema. Se gostou, salve como modelo para reutilizar em outra loja ou outro momento.

Visualizar proposta

Devolve a proposta atual como texto, sem gravar nada. Sem corpo.

POST/api/v1/admin/ai-builder/sessions/{id}/previewAdmin

Visualizar a proposta da sessão

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/preview" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pré-visualização

json

{
  "css": "{\"theme\":{\"primary_color\":\"#B45309\"},\"extended_theme\":{},\"reasoning\":\"...\"}",
  "session_id": "f239c911-be44-459f-93b0-6a5be4101918"
}

Campos da resposta

cssstring

Apesar do nome, não é CSS: é a proposta (current_output) serializada como texto JSON. Sem proposta, vem o comentário /* AI preview - no output yet */.

session_iduuid

Id da sessão.

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	Sessão não existe.	`{"error":"session not found"}`
500	O 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 preview session","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 sessão

Guarda um retrato do tema atual (para o desfazer), grava a proposta na loja e marca a sessão como applied. Se você não enviar banners, usa os banners já gerados na sessão ou gera três novos (veja banners). O corpo é opcional.

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

Aplicar a proposta à loja

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

bannersobject[]

Banners a aplicar.

positionstring

Posição: hero_full, hero_tall, square_grid, wide_card, sidebar, category_header ou mobile_hero.

image_urlstring

URL ou data URI base64 da imagem.

promptstring

Texto usado para gerar.

widthinteger

Largura em pixels.

heightinteger

Altura em pixels.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "banners": []
  }'

Resposta

200Aplicada

json

{
  "status": "applied"
}

Erros

Status	Quando	Corpo de exemplo
400	A sessão ainda não tem proposta.	`{"error":"session has no output to apply"}`
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	Sessão não existe.	`{"error":"session not found"}`
409	A sessão já foi aplicada.	`{"error":"session already applied"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to apply session","detail":"..."}`

Desfazer aplicação

Restaura o retrato do tema guardado ao aplicar e devolve a sessão ao estado active. Só funciona em sessão applied. Veja o aviso acima sobre o que não é desfeito. Sem corpo.

POST/api/v1/admin/ai-builder/sessions/{id}/rollbackAdmin

Restaurar o tema anterior

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/rollback" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desfeita

json

{
  "status": "rolled_back"
}

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	Sessão não existe.	`{"error":"session not found"}`
500	A sessão não está aplicada (`session has not been applied, cannot rollback`). Esta rota devolve `500` e não `409`.	`{"error":"failed to rollback session","detail":"session has not been applied, cannot rollback"}`

Salvar como modelo

Cria um modelo reutilizável a partir da proposta da sessão. Veja modelos.

POST/api/v1/admin/ai-builder/sessions/{id}/save-templateAdmin

Salvar a proposta como modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

namestringobrigatório

Nome do modelo.

descriptionstring

Descrição.

categorystring

Categoria, por exemplo fashion, minimal, ecommerce.

tagsstring[]

Etiquetas.

is_publicbooleanpadrão: false

true mostra o modelo na lista pública.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/save-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Artesanato quente",
    "category": "ecommerce",
    "tags": [
      "artesanal",
      "quente"
    ],
    "is_public": false
  }'

Resposta

201Modelo criado

json

{
  "id": "01f6a13e-841c-483b-b228-ca8df1200b5f",
  "name": "Artesanato quente",
  "description": "",
  "category": "ecommerce",
  "tags": [
    "artesanal",
    "quente"
  ],
  "thumbnail_url": "",
  "output_json": {
    "theme": {
      "primary_color": "#B45309",
      "secondary_color": "#78350F",
      "font_family": "Lato",
      "heading_font": "Cormorant Garamond",
      "store_name": "Casa Aurora"
    },
    "extended_theme": {
      "button_border_radius": "999px"
    },
    "reasoning": "Paleta terrosa para transmitir artesanal."
  },
  "is_public": false,
  "created_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "created_at": "2026-10-11T12:05:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`name` vazio, ou a sessão não tem proposta (`session has no output to save`).	`{"error":"name is required"}`
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	Sessão não existe.	`{"error":"session not found"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to save template","detail":"..."}`

Veja também

API atual/Referência completa/AI Builder

Aplicar e desfazer

Visualiza a proposta, aplica a sessão à loja, desfaz o tema aplicado e salva a proposta como modelo.

Visualizar proposta

Devolve a proposta atual como texto, sem gravar nada. Sem corpo.

POST/api/v1/admin/ai-builder/sessions/{id}/previewAdmin

Visualizar a proposta da sessão

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/preview" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pré-visualização

json

{
  "css": "{\"theme\":{\"primary_color\":\"#B45309\"},\"extended_theme\":{},\"reasoning\":\"...\"}",
  "session_id": "f239c911-be44-459f-93b0-6a5be4101918"
}

Campos da resposta

cssstring

Apesar do nome, não é CSS: é a proposta (current_output) serializada como texto JSON. Sem proposta, vem o comentário /* AI preview - no output yet */.

session_iduuid

Id da sessão.

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	Sessão não existe.	`{"error":"session not found"}`
500	O 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 preview session","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 sessão

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

Aplicar a proposta à loja

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

bannersobject[]

Banners a aplicar.

positionstring

Posição: hero_full, hero_tall, square_grid, wide_card, sidebar, category_header ou mobile_hero.

image_urlstring

URL ou data URI base64 da imagem.

promptstring

Texto usado para gerar.

widthinteger

Largura em pixels.

heightinteger

Altura em pixels.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "banners": []
  }'

Resposta

200Aplicada

json

{
  "status": "applied"
}

Erros

Status	Quando	Corpo de exemplo
400	A sessão ainda não tem proposta.	`{"error":"session has no output to apply"}`
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	Sessão não existe.	`{"error":"session not found"}`
409	A sessão já foi aplicada.	`{"error":"session already applied"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to apply session","detail":"..."}`

Desfazer aplicação

Restaura o retrato do tema guardado ao aplicar e devolve a sessão ao estado active. Só funciona em sessão applied. Veja o aviso acima sobre o que não é desfeito. Sem corpo.

POST/api/v1/admin/ai-builder/sessions/{id}/rollbackAdmin

Restaurar o tema anterior

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/rollback" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desfeita

json

{
  "status": "rolled_back"
}

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	Sessão não existe.	`{"error":"session not found"}`
500	A sessão não está aplicada (`session has not been applied, cannot rollback`). Esta rota devolve `500` e não `409`.	`{"error":"failed to rollback session","detail":"session has not been applied, cannot rollback"}`

Salvar como modelo

Cria um modelo reutilizável a partir da proposta da sessão. Veja modelos.

POST/api/v1/admin/ai-builder/sessions/{id}/save-templateAdmin

Salvar a proposta como modelo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

namestringobrigatório

Nome do modelo.

descriptionstring

Descrição.

categorystring

Categoria, por exemplo fashion, minimal, ecommerce.

tagsstring[]

Etiquetas.

is_publicbooleanpadrão: false

true mostra o modelo na lista pública.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/save-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Artesanato quente",
    "category": "ecommerce",
    "tags": [
      "artesanal",
      "quente"
    ],
    "is_public": false
  }'

Resposta

201Modelo criado

json

{
  "id": "01f6a13e-841c-483b-b228-ca8df1200b5f",
  "name": "Artesanato quente",
  "description": "",
  "category": "ecommerce",
  "tags": [
    "artesanal",
    "quente"
  ],
  "thumbnail_url": "",
  "output_json": {
    "theme": {
      "primary_color": "#B45309",
      "secondary_color": "#78350F",
      "font_family": "Lato",
      "heading_font": "Cormorant Garamond",
      "store_name": "Casa Aurora"
    },
    "extended_theme": {
      "button_border_radius": "999px"
    },
    "reasoning": "Paleta terrosa para transmitir artesanal."
  },
  "is_public": false,
  "created_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "created_at": "2026-10-11T12:05:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`name` vazio, ou a sessão não tem proposta (`session has no output to save`).	`{"error":"name is required"}`
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	Sessão não existe.	`{"error":"session not found"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to save template","detail":"..."}`