API de membres

Gestiona els seients d’equip i els rols — les persones que comparteixen els emissors, insígnies i credencials del teu compte.

Tots els endpoints requereixen autenticació. Vegeu Autenticació. Cada sol·licitud està limitada al compte del propietari autenticat.

Els rols que es poden assignar a través de l’API són admin, editor i viewer. El rol owner està reservat al titular del compte i no es pot assignar ni eliminar.

Llistar membres

Recupera tots els membres i les invitacions pendents del teu compte.

GET /members

Exemple

curl -X GET https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "items": [
    {
      "memberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@acme.example.com",
      "role": "owner",
      "status": "active"
    },
    {
      "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "email": "editor@acme.example.com",
      "role": "editor",
      "status": "pending"
    }
  ]
}

status és active per als membres que han acceptat, o pending per a les invitacions que encara no s’han acceptat.

---

Convidar un membre

Convida una persona al compte per correu electrònic. S’envia a l’adreça un correu electrònic d’invitació amb un enllaç d’acceptació.

POST /members

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
email	string	Sí	Adreça de correu electrònic a convidar (ha de ser un correu vàlid)
role	string	Sí	Rol a assignar — un de admin, editor, viewer

Exemple

curl -X POST https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "email": "editor@acme.example.com",
      "role": "editor"
    }
  }'

Resposta

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

Errors

• 400 — role must be one of admin, editor, viewer
• 400 — adreça de correu electrònic no vàlida o absent
• 400 — seat limit reached — el compte no té seients lliures per al pla (Free: 2, Starter: 5, Pro: 20, incloent-hi el propietari). Elimina un membre o millora el pla.
• 400 — el correu electrònic ja és membre o té una invitació pendent en aquest compte

---

Acceptar una invitació

Accepta una invitació pendent. El correu electrònic de l’usuari autenticat ha de coincidir amb l’adreça a la qual es va enviar la invitació.

POST /members/accept

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
inviteId	string	Sí	L’ID de la invitació del correu electrònic amb l’enllaç d’acceptació

Exemple

curl -X POST https://api.badges.ninja/members/accept \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  }'

Resposta

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "active"
}

Errors

• 400 — email does not match invitation — el correu electrònic amb què s’ha iniciat la sessió difereix del correu convidat
• 404 — invitació no trobada (ja acceptada, cancel·lada, o l’inviteId és incorrecte)

---

Actualitzar el rol d’un membre

Canvia el rol d’un membre existent. Requereix privilegis de propietari o administrador.

POST /members/{memberId}/role

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
memberId	string	Sí	L’ID del membre (paràmetre de ruta)
role	string	Sí	Rol nou — un de admin, editor, viewer

Exemple

curl -X POST https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901/role \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "role": "admin"
    }
  }'

Resposta

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "role": "admin",
  "updated": true
}

Errors

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — membre no trobat

---

Eliminar un membre

Elimina un membre del compte, o cancel·la una invitació pendent. El membre perd immediatament l’accés i el seu seient queda lliure.

DELETE /members/{memberId}

Exemple

curl -X DELETE https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

Una cadena simple:

"member has been removed"

Errors

• 400 — the owner cannot be removed
• 404 — membre no trobat