API atual/Referência completa/Preenchimento de produto com IA

Configurações e teste

Lê e altera as configurações do preenchimento com IA da loja e testa se a IA responde.

Estas três operações controlam como a IA escreve para a sua loja: o idioma padrão, o tamanho máximo da resposta, a criatividade (temperatura), um modelo de instrução próprio e a lista de campos que podem ser gerados. A IA em si (provedor e modelo) é da plataforma e não é configurável por loja.

Use GET para preencher uma tela de configuração e PUT para salvar. O PUT é uma mescla parcial: só as chaves que você mandar mudam, as demais ficam como estão. Use POST /test antes de um lote grande para saber se a IA está respondendo.

GET/api/v1/admin/ai-product-fill/settingsAdmin

Lê as configurações do preenchimento com IA

Privilégio exigido: manage_ai_tools ou manage_catalog. Sem parâmetros.

Exemplo de requisição (ler)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Configurações (padrões, quando nada foi salvo)

json

{
  "temperature": 0.4,
  "language": "pt-BR",
  "max_tokens": 2200
}

Campos da resposta

temperaturenumberpadrão: 0.4

Quanto a IA varia o texto. Valores baixos deixam o resultado mais previsível.

languagestringpadrão: pt-BR

Idioma dos textos gerados quando a chamada não informa language.

max_tokensintegerpadrão: 2200

Tamanho máximo da resposta da IA, em tokens (pedaços de texto). Um valor baixo demais pode cortar a resposta no meio e fazer a geração falhar.

custom_prompt_templatestring

Só aparece se definido. Modelo de instrução próprio da loja, no lugar do padrão.

allowed_fieldsarray

Só aparece se definido. Lista dos campos que podem ser gerados. Ausente ou vazia significa "todos".

Erros (ler)

Status	Quando	Corpo de exemplo
400	A requisição não identifica uma loja.	`{"error":"tenant_required"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_ai_tools` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`

PUT/api/v1/admin/ai-product-fill/settingsAdmin

Altera as configurações do preenchimento com IA

Privilégio exigido: manage_ai_tools ou manage_catalog. Envie só as chaves que quer mudar.

Corpo da requisição

temperaturenumber

Criatividade. Não há validação de faixa: use valores entre 0 e 1.

languagestring

Idioma padrão dos textos, por exemplo pt-BR ou en.

max_tokensinteger

Tamanho máximo da resposta da IA.

custom_prompt_templatestring

Modelo de instrução da loja. Aceita os marcadores {{name}}, {{sku}}, {{base_keywords}}, {{description}}, {{features}}, {{language}} e {{fields}}, trocados pelos dados do produto. Um marcador desconhecido não é removido: ele aparece literal no texto, para um erro de digitação ficar visível. Envie "" para voltar ao padrão.

allowed_fieldsarray

Lista de campos permitidos (description, short_description, meta_title, meta_description, meta_keywords, tags). Os valores não são validados: um nome inexistente é aceito e simplesmente nunca casa com nenhum campo. Para liberar tudo, envie [].

Exemplo de requisição (alterar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/ai-product-fill/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "language": "pt-BR", "max_tokens": 2500, "allowed_fields": ["description", "short_description"] }'

Resposta (alterar)

200Configurações salvas

json

{
  "temperature": 0.4,
  "language": "pt-BR",
  "max_tokens": 2500,
  "allowed_fields": ["description", "short_description"]
}

A resposta tem o mesmo formato do GET, já com os valores mesclados, então você não precisa de uma segunda leitura.

Erros (alterar)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido, ou a requisição não identifica uma loja.	`{"error":"invalid_request_body"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
500	Falha ao gravar.	`{"error":"save_failed","detail":"..."}`

POST/api/v1/admin/ai-product-fill/testAdmin

Testa se a IA da plataforma responde

Privilégio exigido: manage_ai_tools ou manage_catalog. Sem corpo. Faz duas chamadas pequenas à IA (uma de texto, outra no modo JSON, que é o modo de toda geração real) e grava uma linha no histórico (test em caso de sucesso, error em caso de falha).

Exemplo de requisição (testar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta (testar)

200A IA respondeu

json

{
  "ok": true,
  "model_used": "modelo-da-plataforma",
  "message": "connection ok"
}

200A IA falhou (HTTP 200 com ok=false)

json

{
  "ok": false,
  "model_used": "modelo-da-plataforma",
  "message": "texto do erro devolvido pelo provedor"
}

Campos da resposta

okboolean

true se a IA respondeu aos dois testes.

model_usedstring

Identificador do modelo, apenas informativo. Pode faltar.

messagestring

connection ok no sucesso; o motivo da falha quando ok é false.

Erros (testar)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`

Veja também

Configurações e teste

Lê e altera as configurações do preenchimento com IA da loja e testa se a IA responde.

GET/api/v1/admin/ai-product-fill/settingsAdmin

Lê as configurações do preenchimento com IA

Privilégio exigido: manage_ai_tools ou manage_catalog. Sem parâmetros.

Exemplo de requisição (ler)

bash

curl "$BASE_URL/api/v1/admin/ai-product-fill/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Configurações (padrões, quando nada foi salvo)

json

{
  "temperature": 0.4,
  "language": "pt-BR",
  "max_tokens": 2200
}

Campos da resposta

temperaturenumberpadrão: 0.4

Quanto a IA varia o texto. Valores baixos deixam o resultado mais previsível.

languagestringpadrão: pt-BR

Idioma dos textos gerados quando a chamada não informa language.

max_tokensintegerpadrão: 2200

Tamanho máximo da resposta da IA, em tokens (pedaços de texto). Um valor baixo demais pode cortar a resposta no meio e fazer a geração falhar.

custom_prompt_templatestring

Só aparece se definido. Modelo de instrução próprio da loja, no lugar do padrão.

allowed_fieldsarray

Só aparece se definido. Lista dos campos que podem ser gerados. Ausente ou vazia significa "todos".

Erros (ler)

Status	Quando	Corpo de exemplo
400	A requisição não identifica uma loja.	`{"error":"tenant_required"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_ai_tools` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`

PUT/api/v1/admin/ai-product-fill/settingsAdmin

Altera as configurações do preenchimento com IA

Privilégio exigido: manage_ai_tools ou manage_catalog. Envie só as chaves que quer mudar.

Corpo da requisição

temperaturenumber

Criatividade. Não há validação de faixa: use valores entre 0 e 1.

languagestring

Idioma padrão dos textos, por exemplo pt-BR ou en.

max_tokensinteger

Tamanho máximo da resposta da IA.

custom_prompt_templatestring

allowed_fieldsarray

Exemplo de requisição (alterar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/ai-product-fill/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "language": "pt-BR", "max_tokens": 2500, "allowed_fields": ["description", "short_description"] }'

Resposta (alterar)

200Configurações salvas

json

{
  "temperature": 0.4,
  "language": "pt-BR",
  "max_tokens": 2500,
  "allowed_fields": ["description", "short_description"]
}

A resposta tem o mesmo formato do GET, já com os valores mesclados, então você não precisa de uma segunda leitura.

Erros (alterar)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido, ou a requisição não identifica uma loja.	`{"error":"invalid_request_body"}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
500	Falha ao gravar.	`{"error":"save_failed","detail":"..."}`

POST/api/v1/admin/ai-product-fill/testAdmin

Testa se a IA da plataforma responde

Exemplo de requisição (testar)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta (testar)

200A IA respondeu

json

{
  "ok": true,
  "model_used": "modelo-da-plataforma",
  "message": "connection ok"
}

200A IA falhou (HTTP 200 com ok=false)

json

{
  "ok": false,
  "model_used": "modelo-da-plataforma",
  "message": "texto do erro devolvido pelo provedor"
}

Campos da resposta

okboolean

true se a IA respondeu aos dois testes.

model_usedstring

Identificador do modelo, apenas informativo. Pode faltar.

messagestring

connection ok no sucesso; o motivo da falha quando ok é false.

Erros (testar)

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio necessário.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`