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

Preenchimento com IA

Como a Venddor gera textos de catálogo com IA, um produto por vez ou em lote, e como revisar e aplicar o resultado.

O preenchimento de produto com IA escreve por você os textos de um produto: descrição completa, descrição curta, título e descrição de SEO, palavras-chave e tags. Ele serve para o lojista que tem um catálogo grande com fichas quase vazias (só o nome e uma ou duas palavras-chave) e não quer redigir milhares de textos à mão. A IA nunca grava sozinha o que você não pediu: toda geração passa por uma etapa de revisão, e o que foi gravado em lote pode ser desfeito item a item.

Existem dois modos de usar:

  • Individual: você pede os textos de um produto, confere a prévia e só então manda aplicar (Prévia e aplicação).
  • Em lote: você descreve um filtro ("todos os produtos com descrição vazia da categoria X"), a plataforma gera uma proposta para cada produto em segundo plano e você revisa, aprova e aplica (Lotes).
Pontos-chave
  • Gerar e gravar são passos separados. preview só devolve texto; apply é quem escreve no produto.
  • No lote, aprovar um item já o aplica ao produto. Não existe "aprovado, mas ainda não gravado" como estado de espera.
  • Uma proposta vale por 7 dias. Depois disso o item expira, porque o produto pode ter mudado.
  • Se o produto foi editado depois que a proposta foi gerada, o item é marcado como invalidated em vez de sobrescrever a edição.
  • Todas as rotas exigem um administrador com o privilégio manage_ai_tools ou manage_catalog.

Como funciona

Fluxo individual

Prévia (preview)→Revisão no seu sistema→Aplicar (apply)

Ciclo de um lote

queued→running→completed

paused e cancelled são desvios que você provoca; failed existe como valor, mas a geração por item registra o erro no próprio item.

Status do loteSignificado
queuedCriado, a geração ainda vai começar.
runningA plataforma está gerando as propostas, em segundo plano.
pausedVocê pausou. Itens já gerados continuam disponíveis para revisão.
completedTodos os itens foram processados (gerados ou com erro).
cancelledVocê cancelou. Itens ainda não processados viram cancelled; itens já aplicados continuam aplicados.
failedValor reservado para falha do lote inteiro.

Ciclo de um item do lote

Cada produto do filtro vira um item. O item percorre:

queued→generated→approved→applied
Status do itemSignificado
queuedAguardando a geração.
generatedA proposta está pronta e espera revisão.
approvedEstado de passagem: aprovado e prestes a ser gravado. Em geral você não o vê parado.
appliedA proposta foi gravada no produto. Pode ser desfeita com reverter.
rejectedVocê recusou a proposta. Nada foi gravado.
invalidatedO produto mudou (ou sumiu) depois da proposta; a aplicação foi recusada para não sobrescrever o trabalho de alguém.
failedA geração ou a gravação deu erro; o texto do erro vem em error.
expiredA proposta passou de 7 dias sem decisão.
cancelledO lote foi cancelado antes de o item ser gerado.

Conceitos-chave

Campos que a IA preenche

No modo individual, os campos pedidos são: description (HTML), short_description, meta_title, meta_description, meta_keywords e tags. No lote, os nomes mudam um pouco: description, short_description, seo_title, seo_description, image_alt_text (texto alternativo das fotos) e features (características do produto). Veja cada página para a lista exata.

Limites de tamanho aplicados pela plataforma

O servidor corrige o texto depois de gerar: título de SEO até 60 caracteres, descrição de SEO até 160, descrição curta até 240 (cortando em palavra inteira), e palavras-chave e tags saem em minúsculas, sem repetição. Você não precisa conferir a contagem.

Quem pode usar

A rota exige que o administrador tenha manage_ai_tools ou manage_catalog. Administradores completos passam sempre. Sem o privilégio a resposta é 403.

Identificadores

Ids de produto, lote e item são UUID em string. Datas seguem RFC 3339 em UTC.

Endpoints

MétodoCaminhoPara que serveAuth
POST/api/v1/admin/ai-product-fill/previewGerar uma préviaadmin
POST/api/v1/admin/ai-product-fill/applyAplicar a préviaadmin
GET/api/v1/admin/ai-product-fill/settingsLer configuraçõesadmin
PUT/api/v1/admin/ai-product-fill/settingsAlterar configuraçõesadmin
POST/api/v1/admin/ai-product-fill/testTestar a conexão com a IAadmin
GET/api/v1/admin/ai-product-fill/logsHistórico de geraçõesadmin
POST/api/v1/admin/ai-product-fill/batchesCriar loteadmin
GET/api/v1/admin/ai-product-fill/batchesListar lotesadmin
GET/api/v1/admin/ai-product-fill/batches/{id}Consultar loteadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/pausePausar loteadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/resumeRetomar loteadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/cancelCancelar loteadmin
GET/api/v1/admin/ai-product-fill/batches/{id}/itemsListar itens do loteadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/approveAprovar itemadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/rejectRecusar itemadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/items/{itemId}/revertReverter itemadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/approve-allAprovar todosadmin
POST/api/v1/admin/ai-product-fill/batches/{id}/applyAplicar aprovadosadmin

Erros comuns

  • Achar que preview grava. Ele só devolve texto e registra uma linha no histórico. Quem escreve no produto é apply.
  • Pedir um campo fora da lista. fields_to_fill com um nome desconhecido devolve 400 (field "x" is not supported). No lote, nomes inválidos são descartados em silêncio; se sobrar lista vazia, o erro é fields required.
  • Mandar api_key, model ou api_base_url nas configurações. Esses campos não existem mais: o PUT os ignora e o GET seguinte não os mostra. A IA usada é a da plataforma.
  • Aprovar em massa e achar que acabou. approve-all trabalha por até 3 minutos e 500 itens por chamada. O campo remaining diz quantos faltam; repita a chamada até chegar a zero.
  • Chamar a lista de itens sem limit. O padrão são 100 itens, o máximo 500. Lotes grandes pedem filtro por status.
  • Esperar tokens_in e tokens_out preenchidos. Hoje voltam sempre 0.
  • Reverter achando que volta tudo. Reverter restaura apenas a descrição do produto (detalhes).

Próximos passos

Prévia e aplicação
Gere o texto de um produto e grave o que você aprovar.
Lotes
Enriqueça centenas de produtos de uma vez, com revisão.
Configurações
Ajuste idioma, tamanho e campos permitidos.
Anterior
Produtos obrigatórios
Próxima
Prévia e aplicação
Nesta página
  • Como funciona
  • Fluxo individual
  • Ciclo de um lote
  • Ciclo de um item do lote
  • Conceitos-chave
  • Campos que a IA preenche
  • Limites de tamanho aplicados pela plataforma
  • Quem pode usar
  • Identificadores
  • Endpoints
  • Erros comuns
  • Próximos passos