Skip to content
memberfy
US

Atualiza os níveis da comunidade

PUT/api/gamification/levels

Auth
Requires a token
Who can call it:
owner
admin
API key:
gamification:write
X-CommunityId
X-CommunityId Send the X-CommunityId of the community the operation happens in.
Endpoint descriptions come straight from the API specification and are in Portuguese for now. The interface around them is translated.

Troca a escada inteira de níveis. Só owner e admin. Mande todos os níveis, na ordem: o que tem `id` é mantido e atualizado, o que vem sem `id` é criado, e o que ficou de fora é removido (409 quando uma regra de acesso usa o nível).

Regras (422, um erro por campo em `errors[].param`, como `levels[2].minPoints`): de 2 a 20 níveis; o primeiro começa em 0 e não tem requisitos; `minPoints` inteiro e estritamente crescente; `name` de 1 a 40 caracteres e único na comunidade; `imageUrl` opcional, uma imagem enviada por `POST /api/badges/image`. Num nível padrão, `name` vazio ou igual ao nome padrão (em qualquer idioma) mantém o nome traduzido. `requirements`: até 5 por nível, cada um com `actionType` (uma de `eligibleActions`; o ajuste da equipe não vale), `minCount` (1 a 1.000 por semana) e `spaceId` opcional (um espaço da comunidade, só para ação que acontece num espaço; conta o que acontecer a partir de 2026-11-01), sem repetir ação e espaço no mesmo nível (`levels[i].requirements[j].*`).

Salvar recalcula o nível gravado de todos pela regra (semana anterior ou atual), **sem** disparar gatilho nem evento, e responde `changes: { people, up, down }`. Com `dryRun: true` (no corpo ou `?dryRun=true`), só valida e responde quantos mudariam, sem gravar nada (a prévia do editor).

Headers

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

Request body application/json

NameTypeDescription
dryRunoptionalbooleanSó a prévia (quantos sobem e descem); nada é gravado.
levelsrequiredobject[]
levels[].idoptionalstring (uuid)Nível existente (sem `id`, um nível novo).
levels[].nameoptionalstringmax 40
levels[].minPointsrequiredinteger≥ 0
levels[].imageUrloptionalstringURL devolvida por `POST /api/badges/image`.
levels[].requirementsoptionalobject[]
levels[].requirements[].actionTyperequiredstring
levels[].requirements[].minCountrequiredinteger≥ 1, ≤ 1000
levels[].requirements[].spaceIdoptionalstring (uuid)

Responses

StatusDescription
200Os níveis gravados (ou, com `dryRun`, os de antes), no formato do `GET`, mais `changes` e `dryRun`.
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`).
403Autenticado, mas sem permissão para esta operação.
409Um nível removido abre um espaço ou uma seção ("a partir do nível"). `data.spaces` e `data.sections` (`[{ id, title }]`) dizem quais: tire a regra antes.
422Validação, um erro por campo.
500Erro interno do servidor.

curl example

curl -X PUT "https://api.memberfy.net/api/gamification/levels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID" \
  -H "Content-Type: application/json" \
  -d '{"levels":[{}]}'