API d'emissors

Gestiona emissors de credencials — les organitzacions o persones que lliuren credencials.

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

Crear emissor

Crea un nou emissor.

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ó (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 a LinkedIn. Si es defineix, cada pàgina pública d'atorgament 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

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

Notes

• Es comptabilitza contra el límit d'emissors del teu pla (Free: 1, Starter: 5, Pro: il·limitats). Sense descompte de quota.
• Si el correu de l'emissor coincideix amb el correu del teu compte, es verifica automàticament.
• Si el correu és diferent, s'envia un correu de verificació a l'adreça de l'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

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "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": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Verificar 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ó rebut al 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

{
  "statusCode": 200,
  "info": {
    "verified": true
  }
}

---

Eliminar emissor

Elimina un emissor. L'emissor no pot tenir credencials.

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

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Errors

• 400 — l'emissor té credencials o atorgaments i no es pot eliminar (suprimeix-los abans)
• 404 — emissor no trobat

---

Actualitzar emissor

Actualitza els camps d'un emissor no verificat. Un cop verificat, només logo i linkedinOrganizationId queden editables per preservar l'estabilitat de les credencials.

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 (només si no està verificat)
url	string	No	Nova URL (només si no està verificat)
email	string	No	Nou correu (només si no està verificat — envia un nou correu de verificació)
logo	string	No	Nou logotip codificat en Base64
linkedinOrganizationId	string	No	Nou LinkedIn organization ID (o cadena buida per esborrar-lo)

---

Rotar codi de verificació

Invalida l'enllaç de verificació anterior i envia'n un de nou per correu. Només vàlid mentre l'emissor continuï sense verificar.

POST /issuers/{issuerId}/rotate-code

Resposta

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}