Busca global do painel

Procura de uma vez usuários, produtos, pedidos, categorias, sellers e promoções, mostrando só o que o administrador tem permissão de ver.

É a caixa de busca do topo do painel: uma única consulta devolve resultados de seis áreas, agrupados, cada um com um link para a tela de edição. Serve para localizar rápido um cliente pelo nome, e-mail ou CPF, um pedido pelo número, um produto pelo nome ou SKU. Qualquer administrador pode chamar, mas cada grupo só vem se o usuário tiver o privilégio daquela área.

Grupo	Privilégio (qualquer um)
`users`	`manage_users`, `view_users`
`products`	`manage_products`, `manage_catalog`, `view_catalog`
`orders`	`manage_orders`, `view_orders`
`categories`	`manage_categories`, `manage_catalog`, `view_catalog`
`vendors`	`manage_vendors`, `view_vendors` (só sellers ativos)
`promotions`	`view_promotions`, `manage_promotions`

Administradores com acesso total veem todos os grupos.

GET/api/v1/admin/searchAdmin

Busca global do painel

A busca de produtos combina palavras (cada palavra do termo precisa aparecer) com busca por significado, para achar o produto mesmo quando o nome é escrito diferente. A de usuários também casa CPF e CNPJ (o termo pode ser digitado com ou sem máscara). A de pedidos casa o número do pedido, o início do id, o nome do cliente e o número da ordem de compra.

Parâmetros de consulta

qstringobrigatório

Termo procurado. Com menos de 2 caracteres, a resposta é 200 com todos os grupos vazios. Acima de 100 caracteres é cortado.

limitintegerpadrão: 5

Máximo de resultados por grupo, de 1 a 20. Valor inválido volta a 5; acima de 20 vira 20.

typesstring

Lista separada por vírgula dos grupos desejados: users, products, orders, categories, vendors, promotions. Omitido, busca em todos. Uma lista sem nenhum grupo válido não busca em nenhum.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/search?q=maria&types=users,orders&limit=3" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resultados

json

{
  "query": "maria",
  "users": [
    {
      "id": "b9d60dee-7c9e-4245-8340-490b568da908",
      "label": "Maria Pinto",
      "sublabel": "maria.pinto@example.com · CPF 123.456.789-09",
      "type": "user",
      "href": "/admin/users/b9d60dee-7c9e-4245-8340-490b568da908"
    }
  ],
  "products": [],
  "orders": [
    {
      "id": "ea5b43dc-07dd-4e9d-a044-38ea36261d52",
      "label": "#90882",
      "sublabel": "Mariana Costa · refunded · R$ 499,80",
      "type": "order",
      "href": "/admin/orders/ea5b43dc-07dd-4e9d-a044-38ea36261d52"
    }
  ],
  "categories": [],
  "vendors": [],
  "promotions": [],
  "totals": { "categories": 0, "orders": 1, "products": 0, "promotions": 0, "users": 1, "vendors": 0 }
}

Campos da resposta

querystring

O termo usado (já cortado em 100 caracteres).

usersarray

Usuários encontrados.

productsarray

Produtos encontrados.

ordersarray

Pedidos encontrados.

categoriesarray

Categorias encontradas.

vendorsarray

Sellers ativos encontrados.

promotionsarray

Promoções encontradas.

totalsobject

Quantidade de itens devolvidos em cada grupo (no máximo limit). Não é o total de registros que casam.

Campos de cada resultado

iduuid

Id do registro.

labelstring

Título do resultado (nome, número do pedido, nome do produto).

sublabelstring

Linha de apoio: e-mail e CPF do usuário, cliente e status do pedido, SKU do produto.

typestring

userproductordercategoryvendorpromotion

Tipo do resultado.

hrefstring

Caminho da tela de edição no painel (/admin/...), não uma rota da API.

image_urlstring

Imagem, quando o registro tem uma (produtos).

purchase_order_numberstring

Pedidos que vieram de uma ordem de compra: o número dela.

order_numberstring

Pedidos que vieram de uma ordem de compra: o número do pedido.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	O usuário não é administrador	`{"error":"admin access required"}`
500	Falha ao consultar um grupo	`{"error":"user search failed","detail":"..."}`

Veja também

Busca global do painel

Procura de uma vez usuários, produtos, pedidos, categorias, sellers e promoções, mostrando só o que o administrador tem permissão de ver.

Grupo	Privilégio (qualquer um)
`users`	`manage_users`, `view_users`
`products`	`manage_products`, `manage_catalog`, `view_catalog`
`orders`	`manage_orders`, `view_orders`
`categories`	`manage_categories`, `manage_catalog`, `view_catalog`
`vendors`	`manage_vendors`, `view_vendors` (só sellers ativos)
`promotions`	`view_promotions`, `manage_promotions`

Administradores com acesso total veem todos os grupos.

GET/api/v1/admin/searchAdmin

Busca global do painel

Parâmetros de consulta

qstringobrigatório

Termo procurado. Com menos de 2 caracteres, a resposta é 200 com todos os grupos vazios. Acima de 100 caracteres é cortado.

limitintegerpadrão: 5

Máximo de resultados por grupo, de 1 a 20. Valor inválido volta a 5; acima de 20 vira 20.

typesstring

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/search?q=maria&types=users,orders&limit=3" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resultados

json

{
  "query": "maria",
  "users": [
    {
      "id": "b9d60dee-7c9e-4245-8340-490b568da908",
      "label": "Maria Pinto",
      "sublabel": "maria.pinto@example.com · CPF 123.456.789-09",
      "type": "user",
      "href": "/admin/users/b9d60dee-7c9e-4245-8340-490b568da908"
    }
  ],
  "products": [],
  "orders": [
    {
      "id": "ea5b43dc-07dd-4e9d-a044-38ea36261d52",
      "label": "#90882",
      "sublabel": "Mariana Costa · refunded · R$ 499,80",
      "type": "order",
      "href": "/admin/orders/ea5b43dc-07dd-4e9d-a044-38ea36261d52"
    }
  ],
  "categories": [],
  "vendors": [],
  "promotions": [],
  "totals": { "categories": 0, "orders": 1, "products": 0, "promotions": 0, "users": 1, "vendors": 0 }
}

Campos da resposta

querystring

O termo usado (já cortado em 100 caracteres).

usersarray

Usuários encontrados.

productsarray

Produtos encontrados.

ordersarray

Pedidos encontrados.

categoriesarray

Categorias encontradas.

vendorsarray

Sellers ativos encontrados.

promotionsarray

Promoções encontradas.

totalsobject

Quantidade de itens devolvidos em cada grupo (no máximo limit). Não é o total de registros que casam.

Campos de cada resultado

iduuid

Id do registro.

labelstring

Título do resultado (nome, número do pedido, nome do produto).

sublabelstring

Linha de apoio: e-mail e CPF do usuário, cliente e status do pedido, SKU do produto.

typestring

userproductordercategoryvendorpromotion

Tipo do resultado.

hrefstring

Caminho da tela de edição no painel (/admin/...), não uma rota da API.

image_urlstring

Imagem, quando o registro tem uma (produtos).

purchase_order_numberstring

Pedidos que vieram de uma ordem de compra: o número dela.

order_numberstring

Pedidos que vieram de uma ordem de compra: o número do pedido.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	O usuário não é administrador	`{"error":"admin access required"}`
500	Falha ao consultar um grupo	`{"error":"user search failed","detail":"..."}`