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

bash

curl "$BASE_URL/api/v1/admin/intelligence/search/products?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

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
}

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

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","view_catalog","manage_catalog"]}`
400	`q` ausente.	`{"error":"query parameter 'q' is required"}`
500	Falha 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

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/products/reindex?wait=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

202Iniciada em segundo plano

json

{ "status": "started" }

200Concluída (com wait)

json

{ "status": "completed", "indexed": 1240, "skipped": 3 }

Campos da resposta

statusstring

started ou completed.

indexedinteger

Produtos indexados. Só com wait.

skippedinteger

Produtos ignorados. Só com wait.

Erros

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

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

bash

curl "$BASE_URL/api/v1/admin/intelligence/search/customers?q=maria&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Clientes

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
}

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

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

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

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/customers/reindex" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Concluída

json

{ "indexed": 5230, "failed": 0 }

Campos da resposta

indexedinteger

Clientes indexados.

failedinteger

Clientes que falharam.

Erros

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

Veja também

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.

Buscar produtos

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

bash

curl "$BASE_URL/api/v1/admin/intelligence/search/products?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

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
}

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

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","view_catalog","manage_catalog"]}`
400	`q` ausente.	`{"error":"query parameter 'q' is required"}`
500	Falha 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

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/products/reindex?wait=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

202Iniciada em segundo plano

json

{ "status": "started" }

200Concluída (com wait)

json

{ "status": "completed", "indexed": 1240, "skipped": 3 }

Campos da resposta

statusstring

started ou completed.

indexedinteger

Produtos indexados. Só com wait.

skippedinteger

Produtos ignorados. Só com wait.

Erros

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

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

bash

curl "$BASE_URL/api/v1/admin/intelligence/search/customers?q=maria&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Clientes

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
}

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

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

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

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/search/customers/reindex" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Concluída

json

{ "indexed": 5230, "failed": 0 }

Campos da resposta

indexedinteger

Clientes indexados.

failedinteger

Clientes que falharam.

Erros

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