API d'emissors

Gestiona emissors d'insígnies — les organitzacions o persones que emeten insígnies.

Tots els endpoints requereixen autenticació mitjançant la capçalera X-Api-Key. Consulta Autenticació.

Crear un emissor

Crea un nou emissor d'insígnies.

POST /issuers

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
name	string	Sí	Nom de l'organització (mínim 3 caràcters)
url	string	Sí	Lloc web de l'organització (ha de ser una URL HTTP/HTTPS vàlida)
email	string	Sí	Correu de contacte de l'emissor
logo	string	No	Imatge codificada en Base64 (PNG o JPG)
linkedinOrganizationId	string	No	ID numèric de la pàgina d'empresa de LinkedIn. Si s'estableix, cada pàgina pública de credencial d'aquest emissor mostra un botó Add to LinkedIn Profile.

Exemple

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

Resposta

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Notes

• Compta per al límit d'emissors del teu pla (Free: 2, Starter: 5, Pro: 10). No es dedueix cap quota.
• Si el correu de l'emissor coincideix amb el correu del teu compte, l'emissor es verifica automàticament.
• Si el correu és diferent, s'envia un correu de verificació a l'adreça de l'emissor.
• Després de configurar un emissor, fes servir l'API de credencials per començar a emetre credencials amb aquest emissor.

---

Llistar emissors

Recupera tots els emissors que has creat.

GET /issuers

Exemple

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

Resposta

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp és un Unix epoch en mil·lisegons. Quan hi ha més emissors dels que caben en una pàgina, també es retorna un lastEvaluatedKey per a la paginació.

---

Verificar un emissor

Verifica un emissor amb el codi de verificació enviat al seu correu.

POST /issuers/{issuerId}/verify

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
issuerId	string	Sí	L'ID de l'emissor (paràmetre de ruta)
code	string	Sí	El codi de verificació del correu

Exemple

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Resposta

Una cadena simple:

"issuer has been verified"

---

Eliminar un emissor

Elimina un emissor. L'emissor no ha de tenir cap insígnia vinculada.

DELETE /issuers/{issuerId}

Exemple

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

Una cadena simple:

"issuer has been deleted"

Errors

• 400 — l'emissor encara té insígnies vinculades: issuer has {n} badge(s) linked — delete the badges first. L'eliminació només depèn de les insígnies vinculades — les credencials no la bloquegen.
• 404 — emissor no trobat

---

Actualitzar un emissor

Actualitza els camps d'un emissor. Només es poden editar els emissors no verificats — quan un emissor ja està verificat, aquest endpoint retorna 400 verified issuers cannot be edited per preservar l'estabilitat de les credencials. Editar un emissor regenera el seu codi de verificació: si l'email coincideix amb el correu del teu compte, l'emissor es torna a verificar automàticament; si no, s'envia un correu de verificació nou a aquesta adreça.

PUT /issuers/{issuerId}

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
issuerId	string	Sí	L'ID de l'emissor (paràmetre de ruta)
name	string	No	Nou nom
url	string	No	Nova URL
email	string	No	Nou correu (envia un correu de verificació nou tret que coincideixi amb el correu del teu compte)
logo	string	No	Nou logotip codificat en Base64
linkedinOrganizationId	string	No	Nou ID d'organització de LinkedIn (o cadena buida per esborrar-lo)

Resposta

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Errors

• 400 — verified issuers cannot be edited (l'emissor ja està verificat)
• 400 — not authorized (l'emissor pertany a un altre compte)
• 404 — emissor no trobat