Aller au contenu

Lista ou consulta leaderboard

GET/api/gamification/leaderboard

Auth
Jeton requis
Qui peut l’appeler:
owner
admin
Clé d’API:
gamification:read
X-CommunityId
X-CommunityId Envoyez le X-CommunityId de la communauté où l’opération a lieu.
Les descriptions des endpoints viennent directement de la spécification de l’API et sont en portugais pour l’instant. L’interface autour est traduite.

O ranking da comunidade do `X-CommunityId`. Cada linha traz `badges`: `{ id, name, imageUrl, visibility }` dos badges que a pessoa tem agora; os privados (`visibility: private`, o cadeado) só aparecem para a própria pessoa, owner e admin. **Mudou em 2026-10-27:** antes vinha `{ id, name, icon, color }` (sempre vazio).

**Mudou em 2026-10-29:** - `rank` é a posição com empate ("competition ranking": 1, 2, 2, 2, 5): quem tem os mesmos pontos divide a posição, e `isTied: true` marca as linhas empatadas. `isTopThree` é `rank <= 3` (com empate, podem ser mais de três). - `badges` vem com os **8 mais recentes** que quem chama pode ver; `badgeCount` é o total visível (o app mostra "+N"). Os privados continuam fora para quem não é a própria pessoa, owner ou admin, e não entram em `badgeCount`. - `level`: o nível (1 a 9) pelos pontos de todo o tempo (os da seção, com `sectionId`), a mesma régua do `currentUser` de `GET /api/gamification`. - `previousRank`: com `7d` ou `30d`, a posição na janela anterior de mesmo tamanho; null com `all` ou sem pontos naquela janela.

**Mudou em 2026-10-31:** com `period=all` (sem `sectionId`), `totalPoints` é o **total da pessoa na comunidade**, a soma de todas as seções: o mesmo número de `points` no perfil (`GET /api/members/{id}`), na página do membro, nos relatórios e em `{{pontos}}`. `stats.activeMembers` conta pessoas com pontos (antes contava linhas de pontuação, uma por seção), e `levelDistribution` usa o `level` de cada linha.

**Mudou em 2026-10-30:** cada item de `badges` traz também a concessão, como no perfil (`GET /api/members/{id}/badges`), para o mesmo popover: `description`, `grantId`, `source` (`manual`, `rule`, `workflow`, `import`), `sourceRef`, `origin` (`{ type: course|event|workflow|space, id, title, spaceId? }` ou null; `spaceId` só quando quem chama abre aquele espaço) e `awardedAt`. `id` continua sendo o do badge. O `reason` da equipe nunca vem no ranking.

Paramètres

NomEmplacementTypeDescription
periodfacultatifqueryall | 7d | 30d
sectionIdfacultatifquerystring (uuid)
limitfacultatifqueryinteger

En-têtes

NomTypeDescription
X-CommunityIdfacultatifstring (uuid)ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade.

Réponses

StatutDescription
200Operação realizada com sucesso.
400Requisição inválida — falha de validação.
401Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`).
500Erro interno do servidor.

Exemple curl

curl -X GET "https://api.memberfy.net/api/gamification/leaderboard" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"