Vai al contenuto
memberfy
IT

Atualiza os níveis da comunidade

PUT/api/gamification/levels

Auth
Richiede un token
Chi può:
owner
admin
Chiave API:
gamification:write
X-CommunityId
X-CommunityId Invia l’X-CommunityId della community in cui avviene l’operazione.
Le descrizioni degli endpoint provengono dalla specifica dell’API e per ora sono in portoghese. L’interfaccia intorno è tradotta.

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).

Header

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

Corpo della richiesta application/json

NomeTipoDescrizione
dryRunfacoltativobooleanSó a prévia (quantos sobem e descem); nada é gravado.
levelsobbligatorioobject[]
levels[].idfacoltativostring (uuid)Nível existente (sem `id`, um nível novo).
levels[].namefacoltativostringmax 40
levels[].minPointsobbligatoriointeger≥ 0
levels[].imageUrlfacoltativostringURL devolvida por `POST /api/badges/image`.
levels[].requirementsfacoltativoobject[]
levels[].requirements[].actionTypeobbligatoriostring
levels[].requirements[].minCountobbligatoriointeger≥ 1, ≤ 1000
levels[].requirements[].spaceIdfacoltativostring (uuid)

Risposte

CodiceDescrizione
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.

Esempio con curl

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":[{}]}'