API atual/Referência completa/AI Builder

Conversar com a IA

Envia uma mensagem e recebe a proposta atualizada, de uma vez ou em fluxo de eventos.

Cada mensagem pede ou refina algo ("troque o verde por azul-petróleo", "adicione uma página Sobre"). A IA devolve a conversa inteira com sua resposta e uma proposta atualizada em current_output. Nada é gravado na loja até você aplicar a sessão. Respostas levam de alguns segundos a mais de um minuto; para mostrar progresso, use a rota de fluxo.

Enviar mensagem

Grava a mensagem, aciona a IA e devolve a sessão completa quando termina. Os arquivos de referência enviados para a sessão (texto extraído de PDF e DOCX, cores de imagens) entram automaticamente no contexto.

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

Enviar uma mensagem e esperar a resposta

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

messagestringobrigatório

O pedido, em texto livre. Obrigatório e não vazio.

attachment_idsstring[]

Aceito, mas ignorado: os arquivos já enviados com o session_id da sessão entram sozinhos no contexto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero uma loja de artesanato com visual quente, tons terrosos e fonte elegante."
  }'

Resposta

200Sessão com a resposta

json

{
  "id": "f239c911-be44-459f-93b0-6a5be4101918",
  "name": "Nova identidade",
  "status": "active",
  "messages": [
    {
      "role": "user",
      "content": "Quero uma loja de artesanato com visual quente.",
      "created_at": "2026-10-11T12:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Criei uma paleta quente em tons terrosos e um cabeçalho minimalista.",
      "created_at": "2026-10-11T12:00:30Z"
    }
  ],
  "current_output": {
    "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."
  },
  "theme_snapshot": {},
  "layout_snapshot": {},
  "created_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "created_at": "2026-10-11T11:59:00Z",
  "updated_at": "2026-10-11T12:00:30Z",
  "tokens_used": 4120,
  "processing_ms": 18500,
  "model_used": "claude-haiku-4-5-20251001"
}

Campos da resposta

iduuid

Id da sessão.

namestring

Nome da sessão.

statusstring

active (em conversa), applied (já aplicada à loja) ou discarded.

messagesobject[]

Conversa: role (user, assistant ou system), content, attachments[] (quando houver) e created_at.

current_outputobject

Proposta atual da IA. Veja os campos abaixo. Antes da primeira resposta tem theme e extended_theme nulos.

themeobject

Cores, fontes e demais ajustes principais: primary_color, secondary_color, accent_color, bg_color, text_color, font_family, heading_font, border_radius, store_name...

extended_themeobject

Ajustes finos (botões, cards, cabeçalho, rodapé, espaçamentos...), centenas de chaves opcionais como button_border_radius.

layoutsobject

Estrutura de layout proposta, quando houver.

pages_contentobject[]

Páginas estáticas: slug, title, body, seo_title, seo_description, cada texto como mapa de idioma ({"pt-BR": "..."}).

navigationobject

Menus: header_menu, quick_links, footer_about, footer_help, cada item com label (mapa de idioma) e url.

appearance_settingsobject

Ajustes de aparência.

homepage_sectionsobject[]

Seções da home: slug, settings e blocks[] (type, settings).

catalogobject

Categorias e produtos de demonstração: categories[] e products[] (preço e preço de lista em centavos).

reasoningstring

Explicação da IA.

theme_snapshotobject

Retrato do tema antes de aplicar. Usado pelo rollback. {} antes de aplicar.

layout_snapshotobject

Retrato do layout, quando houver.

created_byuuid

Administrador que criou.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

tokens_usedinteger

Tokens consumidos na última resposta.

processing_msinteger

Duração da última resposta, em ms.

model_usedstring

Modelo que respondeu.

applied_atstring

Quando foi aplicada (RFC 3339). Ausente se nunca.

generated_bannersobject[]

Banners gerados para a sessão, quando houver.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`message` vazio.	`{"error":"message 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 send message","detail":"..."}`

Enviar com fluxo

Mesmo efeito da rota anterior, mas a resposta é um fluxo de eventos SSE (text/event-stream) que mostra cada etapa. O corpo da requisição é o mesmo. Leia o fluxo até o evento done ou error.

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

Enviar uma mensagem e acompanhar o progresso

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

messagestringobrigatório

O pedido. Obrigatório e não vazio.

attachment_idsstring[]

Aceito, mas ignorado.

Exemplo de requisição

bash

curl -N -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Troque o verde por azul-petróleo."}'

Resposta

200Fluxo de eventos

text

event: status
data: {"status":"thinking","message":"Analyzing your request..."}

event: status
data: {"status":"loading_settings","message":"Loading AI configuration..."}

event: result
data: {...sessão completa em JSON...}

event: done
data: {"tokens_used":4120,"processing_ms":18500,"model_used":"claude-haiku-4-5-20251001"}

Campos da resposta

statusevento

Etapas: thinking, loading_settings, analyzing e outras. Cada evento traz status e message (em inglês).

resultevento

A sessão completa, igual à resposta da rota sem fluxo.

doneevento

Fim do fluxo: tokens_used, processing_ms, model_used.

errorevento

Falha: {"error": "..."}. O status HTTP já foi enviado como 200.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`message` vazio.	`{"error":"message 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"}`
500	O servidor não suporta fluxo.	`{"error":"streaming not supported"}`

Veja também

API atual/Referência completa/AI Builder

Conversar com a IA

Envia uma mensagem e recebe a proposta atualizada, de uma vez ou em fluxo de eventos.

Enviar mensagem

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

Enviar uma mensagem e esperar a resposta

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

messagestringobrigatório

O pedido, em texto livre. Obrigatório e não vazio.

attachment_idsstring[]

Aceito, mas ignorado: os arquivos já enviados com o session_id da sessão entram sozinhos no contexto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero uma loja de artesanato com visual quente, tons terrosos e fonte elegante."
  }'

Resposta

200Sessão com a resposta

json

{
  "id": "f239c911-be44-459f-93b0-6a5be4101918",
  "name": "Nova identidade",
  "status": "active",
  "messages": [
    {
      "role": "user",
      "content": "Quero uma loja de artesanato com visual quente.",
      "created_at": "2026-10-11T12:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Criei uma paleta quente em tons terrosos e um cabeçalho minimalista.",
      "created_at": "2026-10-11T12:00:30Z"
    }
  ],
  "current_output": {
    "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."
  },
  "theme_snapshot": {},
  "layout_snapshot": {},
  "created_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
  "created_at": "2026-10-11T11:59:00Z",
  "updated_at": "2026-10-11T12:00:30Z",
  "tokens_used": 4120,
  "processing_ms": 18500,
  "model_used": "claude-haiku-4-5-20251001"
}

Campos da resposta

iduuid

Id da sessão.

namestring

Nome da sessão.

statusstring

active (em conversa), applied (já aplicada à loja) ou discarded.

messagesobject[]

Conversa: role (user, assistant ou system), content, attachments[] (quando houver) e created_at.

current_outputobject

Proposta atual da IA. Veja os campos abaixo. Antes da primeira resposta tem theme e extended_theme nulos.

themeobject

Cores, fontes e demais ajustes principais: primary_color, secondary_color, accent_color, bg_color, text_color, font_family, heading_font, border_radius, store_name...

extended_themeobject

Ajustes finos (botões, cards, cabeçalho, rodapé, espaçamentos...), centenas de chaves opcionais como button_border_radius.

layoutsobject

Estrutura de layout proposta, quando houver.

pages_contentobject[]

Páginas estáticas: slug, title, body, seo_title, seo_description, cada texto como mapa de idioma ({"pt-BR": "..."}).

navigationobject

Menus: header_menu, quick_links, footer_about, footer_help, cada item com label (mapa de idioma) e url.

appearance_settingsobject

Ajustes de aparência.

homepage_sectionsobject[]

Seções da home: slug, settings e blocks[] (type, settings).

catalogobject

Categorias e produtos de demonstração: categories[] e products[] (preço e preço de lista em centavos).

reasoningstring

Explicação da IA.

theme_snapshotobject

Retrato do tema antes de aplicar. Usado pelo rollback. {} antes de aplicar.

layout_snapshotobject

Retrato do layout, quando houver.

created_byuuid

Administrador que criou.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

tokens_usedinteger

Tokens consumidos na última resposta.

processing_msinteger

Duração da última resposta, em ms.

model_usedstring

Modelo que respondeu.

applied_atstring

Quando foi aplicada (RFC 3339). Ausente se nunca.

generated_bannersobject[]

Banners gerados para a sessão, quando houver.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`message` vazio.	`{"error":"message 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 send message","detail":"..."}`

Enviar com fluxo

Mesmo efeito da rota anterior, mas a resposta é um fluxo de eventos SSE (text/event-stream) que mostra cada etapa. O corpo da requisição é o mesmo. Leia o fluxo até o evento done ou error.

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

Enviar uma mensagem e acompanhar o progresso

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

messagestringobrigatório

O pedido. Obrigatório e não vazio.

attachment_idsstring[]

Aceito, mas ignorado.

Exemplo de requisição

bash

curl -N -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Troque o verde por azul-petróleo."}'

Resposta

200Fluxo de eventos

text

event: status
data: {"status":"thinking","message":"Analyzing your request..."}

event: status
data: {"status":"loading_settings","message":"Loading AI configuration..."}

event: result
data: {...sessão completa em JSON...}

event: done
data: {"tokens_used":4120,"processing_ms":18500,"model_used":"claude-haiku-4-5-20251001"}

Campos da resposta

statusevento

Etapas: thinking, loading_settings, analyzing e outras. Cada evento traz status e message (em inglês).

resultevento

A sessão completa, igual à resposta da rota sem fluxo.

doneevento

Fim do fluxo: tokens_used, processing_ms, model_used.

errorevento

Falha: {"error": "..."}. O status HTTP já foi enviado como 200.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`message` vazio.	`{"error":"message 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"}`
500	O servidor não suporta fluxo.	`{"error":"streaming not supported"}`