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

Prévia e aplicação

Gera com IA os textos de um produto (prévia) e grava no produto os valores que você aprovar (aplicação).

Use estas duas operações no modo individual, produto a produto. Primeiro você chama preview: a plataforma devolve os textos que a IA sugere, sem tocar no produto. Depois de conferir (e editar, se quiser), você chama apply com os valores finais, e só então o produto é alterado.

A prévia funciona até para um produto que ainda não foi salvo: basta mandar base_fields (nome e palavras-chave) sem product_id. Se você manda product_id, a plataforma completa o que faltou com os dados atuais do produto (nome, SKU, descrição, palavras-chave e características) e, quando o produto tem fotos, elas também são consideradas. O que você mandar em base_fields tem prioridade sobre o que está salvo.

A aplicação grava description e short_description no produto e os campos de SEO (meta_title, meta_description, meta_keywords). Como o produto não tem um campo próprio de tags, tags é gravado em meta_keywords (e, se você mandar os dois, vale meta_keywords). Depois de gravar, a plataforma dispara o evento de produto atualizado, que reindexa a busca e recalcula a nota de qualidade do anúncio.

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

Gera a prévia dos textos de um produto

Privilégio exigido: manage_ai_tools ou manage_catalog.

Corpo da requisição

product_iduuid

Produto existente. Opcional: sem ele, a IA trabalha só com base_fields. Se o id não existir, a plataforma ignora a busca e segue com o que você mandou.

base_fieldsobject

Dados de partida para a IA.

namestring

Nome do produto.

skustring

Código (SKU) do produto.

base_keywordsstring

Palavras-chave soltas, separadas por vírgula, como dica ("cozinha, inox, premium").

descriptionstring

Descrição atual, se houver, para a IA reescrever ou expandir.

featuresarray

Características do produto.

labelstringobrigatório

Nome da característica, por exemplo Cor.

valuestringobrigatório

Valor, por exemplo Vermelho.

fields_to_fillarrayobrigatório

descriptionshort_descriptionmeta_titlemeta_descriptionmeta_keywordstags

Campos a gerar. Pelo menos um. Se a loja restringiu allowed_fields nas configurações, qualquer campo fora da lista dá erro.

languagestring

Idioma do texto, só para esta chamada (por exemplo pt-BR, en). Sem ele vale o idioma das configurações (padrão pt-BR).

Exemplo de requisição (prévia)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1cf8135a-e349-4dbe-ba70-02257b07bf55",
    "base_fields": {
      "name": "Camiseta Premium Algodão",
      "base_keywords": "camiseta, algodão, básica",
      "features": [{ "label": "Cor", "value": "Branca" }]
    },
    "fields_to_fill": ["description", "short_description", "meta_title", "meta_description"],
    "language": "pt-BR"
  }'

Resposta (prévia)

200Prévia gerada

json

{
  "generated": {
    "description": "<p>Camiseta de algodão com caimento confortável para o dia a dia.</p><ul><li>100% algodão</li><li>Modelagem regular</li></ul>",
    "short_description": "Camiseta básica de algodão, confortável e versátil.",
    "meta_title": "Camiseta Premium de Algodão | Básica e Confortável",
    "meta_description": "Camiseta premium de algodão branca, macia e durável. Compre online com entrega para todo o Brasil."
  },
  "tokens_in": 0,
  "tokens_out": 0,
  "model_used": "modelo-da-plataforma",
  "log_id": "ae75df94-b0be-4b8f-b46c-7641aeb4b53e"
}

Campos da resposta

generatedobject

Mapa campo -> texto com os campos pedidos. description vem em HTML simples. Os textos já saem ajustados aos limites (SEO title 60, SEO description 160, descrição curta 240 caracteres; meta_keywords e tags em minúsculas e sem repetição).

tokens_ininteger

Reservado. Hoje sempre 0.

tokens_outinteger

Reservado. Hoje sempre 0.

model_usedstring

Identificador do modelo que respondeu. É só informativo; não dependa do valor.

log_iduuid

Id da linha criada no histórico. Envie-o como preview_log_id ao aplicar.

Erros (prévia)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid_request_body"}`
400	`fields_to_fill` vazio ou ausente.	`{"error":"fields_to_fill is required"}`
400	Campo desconhecido.	`{"error":"field \"bogus\" is not supported"}`
400	Campo fora do `allowed_fields` da loja.	`{"error":"field \"tags\" is not in the tenant's allowed_fields whitelist"}`
400	A resposta da IA não pôde ser lida como JSON, ou o provedor de IA falhou. No segundo caso o corpo traz a mensagem da camada de provedor como veio.	`{"error":"ai response JSON parse: ..."}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem `manage_ai_tools` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
503	A IA não está configurada para a loja.	`{"error":"ai_provider_not_configured","message":"AI provider not configured.","configure_url":"/admin/modules/ai-product-fill"}`

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

Grava no produto os valores aprovados

Privilégio exigido: manage_ai_tools ou manage_catalog.

Corpo da requisição

product_iduuidobrigatório

Produto que será alterado.

accepted_fieldsobjectobrigatório

Mapa campo -> texto final. Chaves aceitas: description, short_description, meta_title, meta_description, meta_keywords, tags. Pelo menos uma. Os textos são gravados como enviados, sem passar de novo pelos limites de tamanho.

preview_log_iduuid

Id devolvido por preview, para ligar a aplicação à prévia no histórico.

Exemplo de requisição (aplicação)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1cf8135a-e349-4dbe-ba70-02257b07bf55",
    "accepted_fields": {
      "short_description": "Camiseta básica de algodão, confortável e versátil.",
      "meta_title": "Camiseta Premium de Algodão | Básica e Confortável"
    },
    "preview_log_id": "ae75df94-b0be-4b8f-b46c-7641aeb4b53e"
  }'

Resposta (aplicação)

200Aplicação concluída

json

{
  "ok": true,
  "log_id": "ce6a9a25-2a28-4c40-82cf-8a9cc3583db4",
  "applied": ["short_description", "meta_title"]
}

200Aplicação parcial (HTTP 200 com ok=false)

json

{
  "ok": false,
  "log_id": "0b1f6c1e-7a60-4c2c-9a4e-2b6a5d3f8e11",
  "applied": ["short_description"],
  "errors": { "tags": "field not in allowed_fields whitelist" }
}

Campos da resposta

okboolean

true quando nenhum campo deu erro.

log_iduuid

Id da linha de histórico da aplicação.

appliedarray

Campos efetivamente gravados.

errorsobject

Só aparece se algo falhou. Mapa campo -> motivo (field not in allowed_fields whitelist, unsupported field) ou as chaves especiais __product_update__ e __seo_update__ quando a gravação do produto ou do SEO falhou.

Erros (aplicação)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid_request_body"}`
400	Falta `product_id`.	`{"error":"product_id is required"}`
400	`accepted_fields` ausente ou vazio.	`{"error":"accepted_fields is required"}`
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: idioma padrão, tamanho máximo e campos permitidos.
Histórico de gerações
Lotes: para muitos produtos de uma vez.

Prévia e aplicação

Gera com IA os textos de um produto (prévia) e grava no produto os valores que você aprovar (aplicação).

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

Gera a prévia dos textos de um produto

Privilégio exigido: manage_ai_tools ou manage_catalog.

Corpo da requisição

product_iduuid

Produto existente. Opcional: sem ele, a IA trabalha só com base_fields. Se o id não existir, a plataforma ignora a busca e segue com o que você mandou.

base_fieldsobject

Dados de partida para a IA.

namestring

Nome do produto.

skustring

Código (SKU) do produto.

base_keywordsstring

Palavras-chave soltas, separadas por vírgula, como dica ("cozinha, inox, premium").

descriptionstring

Descrição atual, se houver, para a IA reescrever ou expandir.

featuresarray

Características do produto.

labelstringobrigatório

Nome da característica, por exemplo Cor.

valuestringobrigatório

Valor, por exemplo Vermelho.

fields_to_fillarrayobrigatório

descriptionshort_descriptionmeta_titlemeta_descriptionmeta_keywordstags

Campos a gerar. Pelo menos um. Se a loja restringiu allowed_fields nas configurações, qualquer campo fora da lista dá erro.

languagestring

Idioma do texto, só para esta chamada (por exemplo pt-BR, en). Sem ele vale o idioma das configurações (padrão pt-BR).

Exemplo de requisição (prévia)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1cf8135a-e349-4dbe-ba70-02257b07bf55",
    "base_fields": {
      "name": "Camiseta Premium Algodão",
      "base_keywords": "camiseta, algodão, básica",
      "features": [{ "label": "Cor", "value": "Branca" }]
    },
    "fields_to_fill": ["description", "short_description", "meta_title", "meta_description"],
    "language": "pt-BR"
  }'

Resposta (prévia)

200Prévia gerada

json

{
  "generated": {
    "description": "<p>Camiseta de algodão com caimento confortável para o dia a dia.</p><ul><li>100% algodão</li><li>Modelagem regular</li></ul>",
    "short_description": "Camiseta básica de algodão, confortável e versátil.",
    "meta_title": "Camiseta Premium de Algodão | Básica e Confortável",
    "meta_description": "Camiseta premium de algodão branca, macia e durável. Compre online com entrega para todo o Brasil."
  },
  "tokens_in": 0,
  "tokens_out": 0,
  "model_used": "modelo-da-plataforma",
  "log_id": "ae75df94-b0be-4b8f-b46c-7641aeb4b53e"
}

Campos da resposta

generatedobject

tokens_ininteger

Reservado. Hoje sempre 0.

tokens_outinteger

Reservado. Hoje sempre 0.

model_usedstring

Identificador do modelo que respondeu. É só informativo; não dependa do valor.

log_iduuid

Id da linha criada no histórico. Envie-o como preview_log_id ao aplicar.

Erros (prévia)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid_request_body"}`
400	`fields_to_fill` vazio ou ausente.	`{"error":"fields_to_fill is required"}`
400	Campo desconhecido.	`{"error":"field \"bogus\" is not supported"}`
400	Campo fora do `allowed_fields` da loja.	`{"error":"field \"tags\" is not in the tenant's allowed_fields whitelist"}`
400	A resposta da IA não pôde ser lida como JSON, ou o provedor de IA falhou. No segundo caso o corpo traz a mensagem da camada de provedor como veio.	`{"error":"ai response JSON parse: ..."}`
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem `manage_ai_tools` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_ai_tools","manage_catalog"]}`
503	A IA não está configurada para a loja.	`{"error":"ai_provider_not_configured","message":"AI provider not configured.","configure_url":"/admin/modules/ai-product-fill"}`

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

Grava no produto os valores aprovados

Privilégio exigido: manage_ai_tools ou manage_catalog.

Corpo da requisição

product_iduuidobrigatório

Produto que será alterado.

accepted_fieldsobjectobrigatório

preview_log_iduuid

Id devolvido por preview, para ligar a aplicação à prévia no histórico.

Exemplo de requisição (aplicação)

bash

curl -X POST "$BASE_URL/api/v1/admin/ai-product-fill/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1cf8135a-e349-4dbe-ba70-02257b07bf55",
    "accepted_fields": {
      "short_description": "Camiseta básica de algodão, confortável e versátil.",
      "meta_title": "Camiseta Premium de Algodão | Básica e Confortável"
    },
    "preview_log_id": "ae75df94-b0be-4b8f-b46c-7641aeb4b53e"
  }'

Resposta (aplicação)

200Aplicação concluída

json

{
  "ok": true,
  "log_id": "ce6a9a25-2a28-4c40-82cf-8a9cc3583db4",
  "applied": ["short_description", "meta_title"]
}

200Aplicação parcial (HTTP 200 com ok=false)

json

{
  "ok": false,
  "log_id": "0b1f6c1e-7a60-4c2c-9a4e-2b6a5d3f8e11",
  "applied": ["short_description"],
  "errors": { "tags": "field not in allowed_fields whitelist" }
}

Campos da resposta

okboolean

true quando nenhum campo deu erro.

log_iduuid

Id da linha de histórico da aplicação.

appliedarray

Campos efetivamente gravados.

errorsobject

Erros (aplicação)

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid_request_body"}`
400	Falta `product_id`.	`{"error":"product_id is required"}`
400	`accepted_fields` ausente ou vazio.	`{"error":"accepted_fields is required"}`
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: idioma padrão, tamanho máximo e campos permitidos.
Histórico de gerações
Lotes: para muitos produtos de uma vez.