API atual/Referência completa/AI Builder

Arquivos e análise de referência

Envia arquivos de referência para a conversa, analisa o site de um concorrente e extrai a paleta de uma imagem.

Para a IA acertar, dê referências: o manual de marca em PDF, o logotipo, o site de um concorrente que o lojista admira. Estas rotas preparam essas referências. Os arquivos enviados com um session_id passam a fazer parte do contexto de todas as mensagens daquela sessão.

Enviar arquivo

Recebe um arquivo por multipart/form-data (limite de 20 MB) e o associa à sessão. De PDF e DOCX o texto é extraído para o contexto da IA.

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

Enviar um arquivo de referência

Requer o privilégio manage_theme.

Corpo da requisição

filefileobrigatório

O arquivo. Obrigatório.

session_iduuid

Sessão à qual associar. Sem ele o arquivo fica sem sessão e não entra no contexto de nenhuma conversa.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@manual-de-marca.pdf" \
  -F "session_id=f239c911-be44-459f-93b0-6a5be4101918"

Resposta

201Arquivo enviado

json

{
  "id": "9c1a2b3c-4d5e-4f60-8a7b-0c1d2e3f4a5b",
  "session_id": "f239c911-be44-459f-93b0-6a5be4101918",
  "file_url": "/uploads/ai-builder/9c1a2b3c-manual-de-marca.pdf",
  "file_name": "manual-de-marca.pdf",
  "file_type": "application/pdf",
  "file_size_bytes": 482113,
  "extracted_text": "Paleta principal...",
  "extracted_colors": [],
  "created_at": "2026-10-11T12:01:00Z"
}

Campos da resposta

iduuid

Id do arquivo (use para excluir).

session_idstring

Sessão associada.

file_urlstring

Caminho público do arquivo, relativo ao domínio da loja.

file_namestring

Nome original.

file_typestring

Tipo MIME informado pelo cliente.

file_size_bytesinteger

Tamanho em bytes.

extracted_textstring

Texto extraído (PDF e DOCX).

extracted_colorsstring[]

Cores extraídas, quando houver.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Arquivo maior que 20 MB ou formulário inválido.	`{"error":"file too large or invalid multipart form","detail":"..."}`
400	Campo `file` ausente.	`{"error":"file is required","detail":"http: no such file"}`
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	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to upload file","detail":"..."}`

Excluir arquivo

Remove o registro do arquivo. A IA deixa de usá-lo nas próximas mensagens.

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

Excluir um arquivo de referência

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do arquivo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/ai-builder/files/9c1a2b3c-4d5e-4f60-8a7b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído

json

{
  "status": "deleted"
}

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	Arquivo não existe.	`{"error":"file not found"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to delete file","detail":"..."}`

Analisar site

Baixa a página (limite de 10 s) e devolve cores dominantes, fontes sugeridas e observações de layout e estilo. Endereços internos ou privados são recusados. Se faltar o esquema, https:// é assumido.

POST/api/v1/admin/ai-builder/analyze-urlAdmin

Analisar o visual de um site

Requer o privilégio manage_theme.

Corpo da requisição

urlstringobrigatório

Endereço do site. Obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/analyze-url" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.exemplo.com.br"
  }'

Resposta

200Análise

json

{
  "url": "https://www.exemplo.com.br",
  "dominant_colors": [
    "#1F2937",
    "#B45309"
  ],
  "font_suggestions": [
    "Lato",
    "Playfair Display"
  ],
  "layout_notes": "Cabeçalho centralizado, hero em tela cheia.",
  "style_notes": "Minimalista, muito espaço em branco.",
  "summary": "Visual sóbrio e elegante."
}

Campos da resposta

urlstring

Endereço analisado.

dominant_colorsstring[]

Cores em hexadecimal.

font_suggestionsstring[]

Fontes sugeridas.

layout_notesstring

Observações de layout.

style_notesstring

Observações de estilo.

summarystring

Resumo.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`url` vazio.	`{"error":"url 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	Endereço não permitido (`url not allowed`), site fora do ar, resposta diferente de 200 ou falha da IA.	`{"error":"failed to analyze URL","detail":"url not allowed: ..."}`

Extrair cores

Baixa a imagem e devolve suas cores predominantes, da mais para a menos presente. Útil para partir da cor do logotipo.

POST/api/v1/admin/ai-builder/extract-colorsAdmin

Extrair a paleta de uma imagem

Requer o privilégio manage_theme.

Corpo da requisição

image_urlstringobrigatório

Endereço da imagem. Obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/extract-colors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://www.exemplo.com.br/logo.png"
  }'

Resposta

200Cores

json

{
  "colors": [
    {
      "hex": "#B45309",
      "rgb": "rgb(180, 83, 9)",
      "percentage": 42.5,
      "name": "Laranja queimado"
    }
  ],
  "palette": [
    "#B45309",
    "#1F2937"
  ]
}

Campos da resposta

colorsobject[]

Cores com hex, rgb, percentage (estimado) e name.

palettestring[]

Só os hexadecimais, em ordem.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`image_url` vazio.	`{"error":"image_url 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	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to extract colors","detail":"..."}`

Veja também

API atual/Referência completa/AI Builder

Arquivos e análise de referência

Envia arquivos de referência para a conversa, analisa o site de um concorrente e extrai a paleta de uma imagem.

Enviar arquivo

Recebe um arquivo por multipart/form-data (limite de 20 MB) e o associa à sessão. De PDF e DOCX o texto é extraído para o contexto da IA.

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

Enviar um arquivo de referência

Requer o privilégio manage_theme.

Corpo da requisição

filefileobrigatório

O arquivo. Obrigatório.

session_iduuid

Sessão à qual associar. Sem ele o arquivo fica sem sessão e não entra no contexto de nenhuma conversa.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@manual-de-marca.pdf" \
  -F "session_id=f239c911-be44-459f-93b0-6a5be4101918"

Resposta

201Arquivo enviado

json

{
  "id": "9c1a2b3c-4d5e-4f60-8a7b-0c1d2e3f4a5b",
  "session_id": "f239c911-be44-459f-93b0-6a5be4101918",
  "file_url": "/uploads/ai-builder/9c1a2b3c-manual-de-marca.pdf",
  "file_name": "manual-de-marca.pdf",
  "file_type": "application/pdf",
  "file_size_bytes": 482113,
  "extracted_text": "Paleta principal...",
  "extracted_colors": [],
  "created_at": "2026-10-11T12:01:00Z"
}

Campos da resposta

iduuid

Id do arquivo (use para excluir).

session_idstring

Sessão associada.

file_urlstring

Caminho público do arquivo, relativo ao domínio da loja.

file_namestring

Nome original.

file_typestring

Tipo MIME informado pelo cliente.

file_size_bytesinteger

Tamanho em bytes.

extracted_textstring

Texto extraído (PDF e DOCX).

extracted_colorsstring[]

Cores extraídas, quando houver.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Arquivo maior que 20 MB ou formulário inválido.	`{"error":"file too large or invalid multipart form","detail":"..."}`
400	Campo `file` ausente.	`{"error":"file is required","detail":"http: no such file"}`
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	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to upload file","detail":"..."}`

Excluir arquivo

Remove o registro do arquivo. A IA deixa de usá-lo nas próximas mensagens.

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

Excluir um arquivo de referência

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do arquivo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/ai-builder/files/9c1a2b3c-4d5e-4f60-8a7b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído

json

{
  "status": "deleted"
}

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	Arquivo não existe.	`{"error":"file not found"}`
500	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to delete file","detail":"..."}`

Analisar site

POST/api/v1/admin/ai-builder/analyze-urlAdmin

Analisar o visual de um site

Requer o privilégio manage_theme.

Corpo da requisição

urlstringobrigatório

Endereço do site. Obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/analyze-url" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.exemplo.com.br"
  }'

Resposta

200Análise

json

{
  "url": "https://www.exemplo.com.br",
  "dominant_colors": [
    "#1F2937",
    "#B45309"
  ],
  "font_suggestions": [
    "Lato",
    "Playfair Display"
  ],
  "layout_notes": "Cabeçalho centralizado, hero em tela cheia.",
  "style_notes": "Minimalista, muito espaço em branco.",
  "summary": "Visual sóbrio e elegante."
}

Campos da resposta

urlstring

Endereço analisado.

dominant_colorsstring[]

Cores em hexadecimal.

font_suggestionsstring[]

Fontes sugeridas.

layout_notesstring

Observações de layout.

style_notesstring

Observações de estilo.

summarystring

Resumo.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`url` vazio.	`{"error":"url 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	Endereço não permitido (`url not allowed`), site fora do ar, resposta diferente de 200 ou falha da IA.	`{"error":"failed to analyze URL","detail":"url not allowed: ..."}`

Extrair cores

Baixa a imagem e devolve suas cores predominantes, da mais para a menos presente. Útil para partir da cor do logotipo.

POST/api/v1/admin/ai-builder/extract-colorsAdmin

Extrair a paleta de uma imagem

Requer o privilégio manage_theme.

Corpo da requisição

image_urlstringobrigatório

Endereço da imagem. Obrigatório.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-builder/extract-colors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://www.exemplo.com.br/logo.png"
  }'

Resposta

200Cores

json

{
  "colors": [
    {
      "hex": "#B45309",
      "rgb": "rgb(180, 83, 9)",
      "percentage": 42.5,
      "name": "Laranja queimado"
    }
  ],
  "palette": [
    "#B45309",
    "#1F2937"
  ]
}

Campos da resposta

colorsobject[]

Cores com hex, rgb, percentage (estimado) e name.

palettestring[]

Só os hexadecimais, em ordem.

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`image_url` vazio.	`{"error":"image_url 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	Falha de banco de dados ou do provedor de IA.	`{"error":"failed to extract colors","detail":"..."}`