Ferramentas de IA
Rotas que usam a Venddor Intelligence como ferramenta direta, sem conversa: buscar por sentido, escrever a descrição de um produto, gerar um banner, montar uma promoção e importar produtos de uma planilha.
Nem toda tarefa pede um bate-papo. Estas rotas devolvem um resultado pronto para uma entrada precisa, e servem a botões do painel ("gerar descrição com IA") e a integrações. Elas geram conteúdo: o texto, a imagem ou o rascunho é uma sugestão que uma pessoa deve revisar antes de publicar.
Como funciona
| Ferramenta | Entrada | Saída | Efeito na loja |
|---|---|---|---|
| Busca por sentido | Texto livre | Produtos ou clientes parecidos com o texto | Nenhum (a reindexação só atualiza o índice) |
| Descrição de produto | Id do produto | Texto sugerido | Nenhum: não grava no produto |
| Banners | Descrição da imagem | Imagem gerada e guardada | Opcional: rascunho de banner inativo |
| Promoções | Pedido em linguagem natural | Rascunho de promoção | Opcional: promoção criada desativada |
| Importação | Arquivo CSV, XLSX ou DOCX | Linhas de produto e resultado da importação | Cria e atualiza produtos (com dry_run você só simula) |
Conceitos-chave
Privilégios
Cada ferramenta tem a sua lista de privilégios, informada na página da rota. Todas aceitam também um administrador total.
Dinheiro
Preços em price, price_centavos, discount_value e semelhantes são inteiros em centavos. Percentuais de promoção são em pontos-base (1000 = 10%).
Dados pessoais
A busca de clientes devolve e-mail e histórico de compras: restrinja o acesso e não registre as respostas em logs.
Rotas
Todas exigem Authorization: Bearer $TOKEN de um administrador.
| Método | Caminho (após /api/v1/admin/intelligence) | Para que serve | Página |
|---|---|---|---|
| GET | /search/products | Buscar produtos por sentido | search |
| POST | /search/products/reindex | Reindexar produtos | search |
| GET | /search/customers | Buscar clientes por sentido | search |
| POST | /search/customers/reindex | Reindexar clientes | search |
| POST | /generate-description | Sugerir a descrição de um produto | generate-description |
| POST | /banners/generate | Gerar um banner | banners |
| GET | /banners/history | Histórico de banners gerados | banners |
| POST | /promotions/generate | Gerar um rascunho de promoção | promotions-generate |
| POST | /import/parse | Ler um arquivo de produtos | import |
| POST | /import/run | Importar ou simular | import |
| GET | /import/runs | Histórico de importações | import |
Erros comuns
- Esperar que
generate-descriptionsalve o texto. Ela só devolve a sugestão; salvar no produto é uma chamada à parte da API de produtos. - Importar sem simular. Rode
import/runcomdry_run: trueprimeiro. A importação sobrescreve nome, descrição, preço e estoque de produtos com o mesmo SKU. - Mandar valores em reais para
import/run. O campo éprice_centavos. - Confiar na leitura do arquivo.
import/parseusa IA para interpretar as colunas; confira as linhas antes de executar. - Gerar banner com a opção desligada. Responde
403com__module_disabled__. - Achar que a busca por sentido substitui a busca da loja. É uma busca interna do painel; a busca da vitrine é outra.