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

Sessões de conversa

Cria, lista, consulta, renomeia e exclui as sessões em que o administrador conversa com a IA sobre o tema.

Uma sessão é uma conversa com a IA sobre a aparência da loja, do pedido inicial ("quero uma loja de artesanato com visual quente") até a proposta final. Ela guarda as mensagens, a proposta atual (current_output) e, depois de aplicada, o retrato do tema anterior para o desfazer. As sessões são da loja, não do usuário: todos os administradores com permissão veem todas.

Criar sessão

Abre uma sessão vazia no estado active. Em seguida, envie mensagens.

POST/api/v1/admin/ai-builder/sessionsAdmin

Criar uma sessão

Requer o privilégio manage_theme.

Corpo da requisição

namestringpadrão: Untitled Session
Nome da sessão.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-builder/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nova identidade"
  }'

Resposta

201Sessão criada
json
{
  "id": "f239c911-be44-459f-93b0-6a5be4101918",
  "name": "Nova identidade",
  "status": "active",
  "messages": [],
  "current_output": {
    "theme": null,
    "extended_theme": null,
    "reasoning": ""
  },
  "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": 0,
  "processing_ms": 0,
  "model_used": ""
}

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

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
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 create session","detail":"..."}

Listar sessões

Devolve todas as sessões da loja, sem filtro nem paginação.

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

Listar as sessões da loja

Requer o privilégio manage_theme.

Exemplo de requisição

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

Resposta

200Sessões
json
{
  "sessions": [
    {
      "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

sessionsarray

Sessões.

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

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 sessions","detail":"..."}

Obter sessão

Devolve a sessão com toda a conversa e a proposta atual.

GET/api/v1/admin/ai-builder/sessions/{id}Admin

Obter uma 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 GET "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sessão
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

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"}
404Sessão não existe.{"error":"session 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 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."}

Renomear sessão

Troca o nome e devolve a sessão atualizada.

PATCH/api/v1/admin/ai-builder/sessions/{id}Admin

Renomear uma sessão

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Corpo da requisição

namestringobrigatório
Novo nome.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Identidade outono"
  }'

Resposta

200Sessão renomeada
json
{
  "id": "f239c911-be44-459f-93b0-6a5be4101918",
  "name": "Identidade outono",
  "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

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
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"}
404Sessão não existe.{"error":"session 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 rename 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."}

Excluir sessão

Remove a sessão e a conversa. Isso não desfaz o que a sessão já aplicou à loja.

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

Excluir uma 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 DELETE "$BASE_URL/api/v1/admin/ai-builder/sessions/f239c911-be44-459f-93b0-6a5be4101918" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída
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"}
404Sessão não existe.{"error":"session 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 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."}

Veja também

  • AI Builder: visão geral
  • Conversar com a IA
Anterior
AI Builder
Próxima
Conversar com a IA
Nesta página
  • Criar sessão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar sessões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Obter sessão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Renomear sessão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir sessão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também