Players API

Busca e perfil completo de jogadores — fonte agregada de identidade, finanças, propriedades, veículos, multas e jobs.

Duas rotas expostas pelo resource Lua, consumidas pelo backend via bridge:

GET/elite-saas/player/search?q=<query>🔒 auth

Pesquisa por nome (LIKE), userId numérico exato ou CPF/documento. Retorna até 20 matches.

Query parameters

q

stringrequired

Termo de busca. Aceita nome parcial, userId puro (123) ou CPF. Espaços e %hex são decodificados.

200 OK

json

{
  "query": "joão",
  "count": 2,
  "players": [
    {
      "userId": 4823,
      "name": "João Pereira",
      "document": "123.456.789-00",
      "isOnline": true,
      "serverId": 7
    },
    {
      "userId": 9012,
      "name": "João Silva",
      "document": null,
      "isOnline": false,
      "serverId": null
    }
  ]
}

Como o painel usa

Quando o usuário clica em um player da lista Online, o painel passa ?userId=<n> direto pro perfil — pulando a busca. Sem userId (vRP indisponível) cai pra ?q=<nome>&auto=1.

GET/elite-saas/player/<userId>🔒 auth

Perfil completo agregado. Resiliente a falha parcial — cada seção tem pcall isolado.

Path parameter

userId

integerrequired

ID do jogador na tabela vrp_users.id.

200 OK

json

{
  "userId": 4823,
  "generatedAt": "2026-05-24T22:10:11Z",
  "partialErrors": null,
  "identity": {
    "name": "João Pereira",
    "document": "123.456.789-00",
    "phone": "(11) 99999-1234",
    "dateOfBirth": "1995-03-12",
    "sex": "M",
    "nationality": "BR",
    "licenses": { "steam": "...", "discord": "...", "fivem": "..." },
    "whitelisted": true,
    "banned": false,
    "banReason": null,
    "firstSeen": "2024-01-10T03:14:00Z",
    "lastSeen": "2026-05-24T21:50:11Z"
  },
  "money": { "wallet": 12450, "bank": 850000, "paypal": 0 },
  "summary": {
    "totalMoney": 862450,
    "propertiesCount": 2,
    "vehiclesCount": 5,
    "inventorySlots": 28,
    "totalFines": 3,
    "pendingFines": 1,
    "pendingFineAmount": 2500
  },
  "properties": [ { "propertyId": "ap-001", "label": "Apartamento Vinewood" } ],
  "vehicles":   [ { "plate": "ABC1D23", "model": "adder", "category": "super", "garage": "legion", "stolen": false, "value": 1000000 } ],
  "inventory":  [ { "slot": 1, "item": "bandagem", "label": "Bandagem", "amount": 5, "weight": 100 } ],
  "relationships": [],
  "fines":  [ { "fineId": 42, "reason": "Excesso de velocidade", "amount": 2500, "paid": false, "issuedBy": "Polícia", "issuedAt": "2026-05-20T14:00:00Z" } ],
  "jobs":   { "job": { "label": "Mecânico", "gradeLabel": "Sênior", "onDuty": true }, "gang": null }
}

Erros parciais

Quando uma das seções falha (ex.: adapter de relacionamentos não implementado), partialErrors traz o detalhe e o restante do payload vem normal:

json

{
  "userId": 4823,
  "partialErrors": {
    "relationships": "função getRelationships não implementada",
    "fines": "tabela bank_fines não existe"
  },
  "identity": { ... }
  /* outros campos podem estar null */
}

Open-schema em properties e vehicles

Os campos properties[*] e vehicles[*] aceitam chaves arbitrárias além dos obrigatórios — o painel as renderiza dinamicamente. Você pode devolver iptu, residentes, preco, ipva, etc., direto do seu adapter, e o painel mostra como linhas chave/valor.

Veja adapter player_search para o contrato SQL completo (quais tabelas/colunas o resource lê).

Códigos de erro

400

optional

Header x-tenant-id ausente ou diferente de Config.TenantSlug.

401

optional

Bearer ausente ou não bate com Config.ServerLinkToken.

503

optional

O ficheiro functions/player_search.lua não foi carregado (e.g. erro de sintaxe). Confira o console do FX.

AnteriorTroubleshooting Próxima Metrics & Health