Pesquisa Global — Guia de Integracao

Endpoint para pesquisar em qualquer collection do sistema. Admin only.

Rota: GET /api/v1/search/{collection_name} Auth: Bearer token (JWT) + user_type='admin'

---

Formato

GET /api/v1/search/{collection_name}?search=JSON
Authorization: Bearer <admin_token>

O parametro search e um JSON com:

Campo	Tipo	Obrigatorio	Descricao
value	string, int ou float	Sim	Valor a pesquisar
key	string	Nao	Campo especifico para buscar. Se omitido, busca em todos os campos compativeis

---

Deteccao de Tipo

O tipo do value no JSON determina onde a busca e feita:

JSON	Tipo detectado	Comportamento
{"value":"goiania"}	string	Regex accent-insensitive em campos texto
{"value":160}	int	Match exato em campos numericos (int, float)
{"value":50.00}	float	Match exato em campos numericos
{"value":"69c1dad..."}	ObjectId	Match exato em campos OID (_id, FKs)

Importante: {"value":"160"} (string) busca o texto "160" em campos texto. {"value":160} (numero) busca o valor 160 em campos numericos. O tipo JSON e respeitado.

---

Collections Disponiveis

users, customers, events, tickets, ticket_orders, promo_codes, subscriptions, plans, videos, categories, seasons, series, webhook_logs

---

Parametros de Paginacao

Mesmos parametros das rotas de entidade:

Param	Default	Descricao
sort	{"register_update_date":-1}	Criterio de ordenacao (JSON)
docs_range	(0, 0)	Range de documentos
qty_docs_page	10	Documentos por pagina
current_page	0	Pagina atual (0-based)

---

Exemplos

Buscar em todos os campos (sem key)

GET /api/v1/search/events?search={"value":"goiania"}
Authorization: Bearer <admin_token>

Busca "goiania" em todos os campos texto do Event. Accent-insensitive: encontra "Goiania".

Buscar em campo especifico (com key)

GET /api/v1/search/customers?search={"key":"email","value":"maria"}
Authorization: Bearer <admin_token>

Busca "maria" apenas no campo email.

Buscar por ObjectId

GET /api/v1/search/events?search={"value":"69c1dadce9c9cdd70fe6b58c"}
Authorization: Bearer <admin_token>

Detecta ObjectId automaticamente. Busca em _id e campos FK (OID).

Buscar por valor numerico

GET /api/v1/search/events?search={"key":"capacity","value":360}
Authorization: Bearer <admin_token>

Busca eventos com capacity=360. Note: value e numero (sem aspas).

Com paginacao e ordenacao

GET /api/v1/search/customers?search={"value":"maria"}&qty_docs_page=5&current_page=2&sort={"email":1}
Authorization: Bearer <admin_token>

---

Response

Formato padrao 200 (mesmo de todas as rotas de entidade):

{
  "docs": [
    {
      "_id": "69c1dadce9c9cdd70fe6b58c",
      "title": "A Escolha de Ficar - Goiania",
      "event_type": "movie_premiere",
      "capacity": 160
    }
  ],
  "links": [],
  "msg": "ok",
  "info": null,
  "pagination": {
    "current_page": 0,
    "qty_docs_page": 10,
    "qty_of_pages": 1,
    "qty_total_docs": 1
  }
}

---

Erros

HTTP	Cenario
400	Collection nao disponivel para pesquisa
400	JSON invalido no parametro search
400	Campo value ausente no JSON
403	Usuario nao e admin
401	Token ausente ou invalido

---

Flutter/Dart

/// Pesquisa global em qualquer collection.
///
/// [collection] — nome da collection (ex: 'customers', 'events')
/// [value] — valor a pesquisar (String, int ou double)
/// [key] — campo especifico (opcional, null = todos os campos)
Future<Map<String, dynamic>> search({
  required String token,
  required String collection,
  required dynamic value,
  String? key,
  int page = 0,
  int perPage = 10,
  String sort = '{"register_update_date":-1}',
}) async {
  final searchJson = key != null
      ? jsonEncode({'key': key, 'value': value})
      : jsonEncode({'value': value});

  final response = await dio.get(
    '/api/v1/search/$collection',
    queryParameters: {
      'search': searchJson,
      'current_page': page,
      'qty_docs_page': perPage,
      'sort': sort,
    },
    options: Options(headers: {'Authorization': 'Bearer $token'}),
  );
  return response.data;
}

// Exemplos de uso:

// Buscar customer por nome (todos os campos)
final results = await search(
  token: adminToken,
  collection: 'customers',
  value: 'maria',
);

// Buscar por email especifico
final results = await search(
  token: adminToken,
  collection: 'customers',
  value: 'maria',
  key: 'email',
);

// Buscar evento por capacidade (numero)
final results = await search(
  token: adminToken,
  collection: 'events',
  value: 160,
  key: 'capacity',
);

// Buscar por ObjectId
final results = await search(
  token: adminToken,
  collection: 'events',
  value: '69c1dadce9c9cdd70fe6b58c',
);