AI Builder

Geração de temas por conversa com IA: sessões, referências, modelos, aplicação com desfazer, ajustes do provedor e banners.

O AI Builder deixa o lojista descrever o visual que quer numa conversa ("loja de artesanato, tons terrosos, fonte elegante") e recebe de volta um tema completo: cores, fontes, menus, páginas, seções da home e até categorias e produtos de demonstração. A proposta fica numa sessão até alguém aplicá-la à loja. Também há modelos prontos, análise de site de referência e geração de banners.

Como funciona

O fluxo normal tem seis passos, e só o penúltimo mexe na loja.

Sessão→Referências→Conversa→Visualizar→Aplicar→Desfazer (opcional)

Configure o provedor
PUT /settings com a chave e enabled: true; valide com POST /test-connection.
Abra uma sessão
POST /sessions.
Dê referências (opcional)
POST /files com session_id, POST /analyze-url, POST /extract-colors.
Converse
POST /sessions/{id}/message, ou /stream para ver o progresso. Repita para refinar.
Confira
POST /sessions/{id}/preview mostra a proposta atual.
Aplique
POST /sessions/{id}/apply. Se não gostar, POST /sessions/{id}/rollback restaura o tema.

Estados da sessão (campo status):

Valor	Significado
`active`	Em conversa. É o estado após criar e após um rollback.
`applied`	A proposta foi aplicada à loja. Não pode ser aplicada de novo (`409`).
`discarded`	Descartada.

Conceitos-chave

Provedor de IA

A loja escolhe em active_provider entre anthropic e openai_compatible (um modelo próprio, por endereço). As chaves ficam guardadas por loja e voltam mascaradas.

Proposta (`current_output`)

É o resultado estruturado da IA: theme, extended_theme, layouts, pages_content, navigation, appearance_settings, homepage_sections, catalog e reasoning. Valores monetários do catálogo estão em centavos (inteiros).

Modelos

Uma proposta pode ser guardada como modelo e aplicada em qualquer momento, sem nova conversa. Aplicar um modelo não guarda retrato, então não há desfazer.

Segurança das chaves

GET /settings e PUT /settings nunca devolvem uma chave inteira. Só POST /settings/reveal-key revela, uma por vez, e deixa registro de auditoria.

Relação com o Theme Builder

O AI Builder escreve o tema da loja e, quando a proposta traz homepage_sections, as seções da home do Theme Builder.

Endpoints

Método	Caminho	Para que serve	Página
`POST`	`/api/v1/admin/ai-builder/sessions`	Criar uma sessão	Sessões de conversa
`GET`	`/api/v1/admin/ai-builder/sessions`	Listar as sessões da loja	Sessões de conversa
`GET`	`/api/v1/admin/ai-builder/sessions/{id}`	Obter uma sessão	Sessões de conversa
`PATCH`	`/api/v1/admin/ai-builder/sessions/{id}`	Renomear uma sessão	Sessões de conversa
`DELETE`	`/api/v1/admin/ai-builder/sessions/{id}`	Excluir uma sessão	Sessões de conversa
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/message`	Enviar uma mensagem e esperar a resposta	Conversar com a IA
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/stream`	Enviar uma mensagem e acompanhar o progresso	Conversar com a IA
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/preview`	Visualizar a proposta da sessão	Aplicar e desfazer
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/apply`	Aplicar a proposta à loja	Aplicar e desfazer
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/rollback`	Restaurar o tema anterior	Aplicar e desfazer
`POST`	`/api/v1/admin/ai-builder/sessions/{id}/save-template`	Salvar a proposta como modelo	Aplicar e desfazer
`POST`	`/api/v1/admin/ai-builder/files`	Enviar um arquivo de referência	Arquivos e análise de referência
`DELETE`	`/api/v1/admin/ai-builder/files/{id}`	Excluir um arquivo de referência	Arquivos e análise de referência
`POST`	`/api/v1/admin/ai-builder/analyze-url`	Analisar o visual de um site	Arquivos e análise de referência
`POST`	`/api/v1/admin/ai-builder/extract-colors`	Extrair a paleta de uma imagem	Arquivos e análise de referência
`GET`	`/api/v1/admin/ai-builder/templates`	Listar todos os modelos	Modelos de tema
`GET`	`/api/v1/admin/ai-builder/templates/public`	Listar só os modelos públicos	Modelos de tema
`GET`	`/api/v1/admin/ai-builder/templates/{id}`	Obter um modelo	Modelos de tema
`DELETE`	`/api/v1/admin/ai-builder/templates/{id}`	Excluir um modelo	Modelos de tema
`POST`	`/api/v1/admin/ai-builder/templates/{id}/apply`	Aplicar um modelo à loja	Modelos de tema
`POST`	`/api/v1/admin/ai-builder/templates/seed`	Criar os modelos de fábrica	Modelos de tema
`GET`	`/api/v1/admin/ai-builder/settings`	Obter os ajustes	Ajustes do AI Builder
`PUT`	`/api/v1/admin/ai-builder/settings`	Salvar os ajustes	Ajustes do AI Builder
`POST`	`/api/v1/admin/ai-builder/settings/reveal-key`	Revelar uma chave	Ajustes do AI Builder
`POST`	`/api/v1/admin/ai-builder/test-connection`	Testar a conexão com o provedor	Ajustes do AI Builder
`POST`	`/api/v1/admin/ai-builder/generate-banner`	Gerar um banner a partir de um texto	Gerar banners
`POST`	`/api/v1/admin/ai-builder/generate-theme-banners`	Gerar o conjunto de 3 banners do tema	Gerar banners

Erros comuns

Tratar 200 de /message como sucesso. Se a IA estiver desligada ou sem chave, a resposta é 200 com uma mensagem do assistente avisando.
Aplicar sem visualizar e esperar que o desfazer reverta tudo. Ele restaura só o tema; páginas, menus, produtos e banners criados ficam.
Aplicar um modelo em produção contando com desfazer. Não há retrato nessa rota.
Enviar PUT /settings parcial. Todos os campos são gravados; os omitidos voltam ao vazio. Leia, altere e devolva o objeto completo.
Mandar attachment_ids esperando anexar arquivos. O campo é ignorado: envie o arquivo com session_id.
Ler o status HTTP do /stream. O fluxo começa com 200; falhas chegam como evento error.
Esperar banners sob medida de generate-theme-banners. Os três textos são fixos e ignoram os dados da loja.

Próximos passos

Ajustes

Comece configurando o provedor.

Conversar com a IA

Mensagens e fluxo de progresso.

Aplicar e desfazer

O que a aplicação grava e o que o desfazer restaura.

Theme Builder

Edição manual do tema por seções.

API atual/Referência completa