Saltar al contenido
memberfy
AR

Atualiza os níveis da comunidade

PUT/api/gamification/levels

Auth
Requiere token
Quién puede:
owner
admin
Clave de API:
gamification:write
X-CommunityId
X-CommunityId Envía el X-CommunityId de la comunidad en la que ocurre la operación.
Las descripciones de los endpoints vienen de la especificación de la API y, por ahora, están en portugués. La interfaz alrededor está traducida.

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

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

Cuerpo de la solicitud application/json

NombreTipoDescripción
dryRunopcionalbooleanSó a prévia (quantos sobem e descem); nada é gravado.
levelsobligatorioobject[]
levels[].idopcionalstring (uuid)Nível existente (sem `id`, um nível novo).
levels[].nameopcionalstringmax 40
levels[].minPointsobligatoriointeger≥ 0
levels[].imageUrlopcionalstringURL devolvida por `POST /api/badges/image`.
levels[].requirementsopcionalobject[]
levels[].requirements[].actionTypeobligatoriostring
levels[].requirements[].minCountobligatoriointeger≥ 1, ≤ 1000
levels[].requirements[].spaceIdopcionalstring (uuid)

Respuestas

CódigoDescripción
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.

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