VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Busca por sentido

Procura produtos e clientes pelo significado do texto e reconstrói os índices dessas buscas.

A busca por sentido acha "tênis de corrida leve" mesmo que nenhum produto tenha exatamente essas palavras. Quando o índice não cobre tudo, a plataforma completa o resultado com uma busca por texto simples; o campo source de cada resultado diz de qual veio. Há uma busca de produtos e outra de clientes, cada uma com a sua rota de reindexação.

Buscar produtos

Devolve os produtos mais parecidos com o texto, com preço em centavos e um índice de semelhança. Se o recurso estiver desligado, devolve lista vazia (não um erro). Um administrador de vendedor (user_type vendor) só vê produtos do próprio vendedor.

GET/api/v1/admin/intelligence/search/productsAdmin

Buscar produtos por sentido

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

qstringobrigatório
Texto da busca.
limitintegerpadrão: 20
Quantidade. Padrão 20, teto 100.
vendor_iduuid
Restringe a um vendedor. Ignorado para administradores de vendedor.

Exemplo de requisição

Resposta

200Produtos

Campos da resposta

hits[].product_iduuid
Id do produto.
hits[].vendor_iduuid
Vendedor dono do produto.
hits[].namestring
Nome.
hits[].skustring
SKU. Pode faltar.
hits[].priceinteger
Preço em centavos.
hits[].statusstring
Estado do produto (letra, como A ativo).
hits[].similaritynumber
0 a 1; maior é mais parecido.
hits[].sourcestring
vectorilike
De onde veio o resultado.
countinteger
Quantidade de resultados.
sourcestring
Fonte do primeiro resultado, ou empty se não houve nenhum.
took_msinteger
Tempo da busca, em milissegundos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","view_catalog","manage_catalog"]}
400q ausente.{"error":"query parameter 'q' is required"}
500Falha na busca.{"error":"search failed: ..."}

Reindexar produtos

Recalcula o índice de busca de todos os produtos. Por padrão não espera: responde 202 e roda em segundo plano. Com wait verdadeiro, espera terminar e devolve as contagens.

POST/api/v1/admin/intelligence/search/products/reindexAdmin

Reindexar produtos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

waitstring
1true
1 ou true para esperar. Também aceito como wait: true no corpo JSON.

Exemplo de requisição

Resposta

202Iniciada em segundo plano
200Concluída (com wait)

Campos da resposta

statusstring
started ou completed.
indexedinteger
Produtos indexados. Só com wait.
skippedinteger
Produtos ignorados. Só com wait.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","manage_settings"]}
500Falha na reindexação (com wait).{"error":"reindex failed: ..."}
Pode demorar

Em catálogos grandes, wait=true pode levar minutos. Prefira o modo padrão e consulte a busca depois.

Buscar clientes

Procura clientes pelo texto (nome, e-mail, perfil de compra) e devolve gasto total e número de pedidos de cada um.

GET/api/v1/admin/intelligence/search/customersAdmin

Buscar clientes por sentido

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

qstringobrigatório
Texto da busca.
limitintegerpadrão: 10
Quantidade. Padrão 10, teto 100.

Exemplo de requisição

Resposta

200Clientes

Campos da resposta

matches[].user_iduuid
Id do cliente.
matches[].emailstring
E-mail.
matches[].full_namestring
Nome completo (razão social, para empresas).
matches[].person_typestring
PF ou PJ. Pode faltar.
matches[].trade_namestring
Nome fantasia, para empresas. Pode faltar.
matches[].similaritynumber
0 a 1. Vale 0 quando o resultado veio de busca por texto.
matches[].lifetime_spend_centavosinteger
Soma dos pedidos pagos, em centavos.
matches[].order_countinteger
Todos os pedidos principais do cliente (sem filtro de status).
matches[].last_order_atstring
RFC 3339. Pode faltar.
totalinteger
Quantidade devolvida.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["view_users","manage_users"]}
400q ausente.{"error":"q parameter required"}
503Recurso desligado, sem provedor de IA ou sem a extensão de busca no banco.{"error":"intelligence: vector customer search is disabled ..."}
Dados pessoais

A resposta traz e-mail e valor gasto. Dê o privilégio view_users só a quem pode ver clientes.

Reindexar clientes

Recalcula o índice de busca de todos os clientes e espera terminar antes de responder.

POST/api/v1/admin/intelligence/search/customers/reindexAdmin

Reindexar clientes

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Exemplo de requisição

Resposta

200Concluída

Campos da resposta

indexedinteger
Clientes indexados.
failedinteger
Clientes que falharam.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_users","manage_settings"]}
503Mesmas condições da busca.{"error":"intelligence: ..."}
Resposta demorada

A chamada é síncrona e proporcional ao número de clientes. Use um timeout longo.

Veja também

  • Visão geral
  • Conversas
Anterior
Ferramentas de IA
Próxima
Descrição de produto por IA
Nesta página
  • Buscar produtos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reindexar produtos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Buscar clientes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reindexar clientes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/intelligence/search/products?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/products/reindex?wait=true" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/intelligence/search/customers?q=maria&limit=5" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/customers/reindex" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "count": 1,
  "hits": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "price": 30000,
      "status": "A",
      "similarity": 0.6,
      "source": "ilike"
    }
  ],
  "source": "ilike",
  "took_ms": 577
}
json
{ "status": "started" }
json
{ "status": "completed", "indexed": 1240, "skipped": 3 }
json
{
  "matches": [
    {
      "user_id": "b9d60dee-7c9e-4245-8340-490b568da908",
      "email": "maria.pinto@example.com",
      "full_name": "Maria Pinto",
      "similarity": 0,
      "indexed_at": "0001-01-01T00:00:00Z",
      "lifetime_spend_centavos": 872160,
      "order_count": 12,
      "last_order_at": "2026-08-31T11:25:13.98218Z"
    }
  ],
  "total": 1
}
json
{ "indexed": 5230, "failed": 0 }