API de credencials

Gestiona plantilles de credencials — les que lliures als destinataris.

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

Crear credencial

Crea una credencial sota un emissor verificat.

POST /badges

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
name	string	Sí	Títol de la credencial
description	string	Sí	Què representa la credencial
criteria	string	Sí	Què va fer el destinatari per obtenir-la
image	string	Sí	Imatge codificada en Base64 (PNG o JPG)
issuerId	string	Sí	L'ID de l'emissor verificat

Exemple

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Resposta

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
  }
}

Notes

• L'emissor ha d'estar verificat abans de crear credencials.
• La imatge es puja a IPFS per a un emmagatzematge perenne.

---

Llistar credencials

Recupera totes les credencials que has creat.

GET /badges

Exemple

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

Resposta

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
        "image": "https://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Actualitzar credencial

Actualitza una credencial existent. Només canvien els camps que hi envies.

PUT /badges/{badgeId}

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la credencial (paràmetre de ruta)
name	string	No	Nou títol
description	string	No	Nova descripció
criteria	string	No	Nous criteris
image	string	No	Nova imatge en Base64

Exemple

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Resposta

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "updated": true
  }
}

---

Actualitzar text de difusió

Fixa el text personalitzat mostrat quan els destinataris difonen aquesta credencial a xarxes socials.

PUT /badges/{badgeId}/share-text

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la credencial (paràmetre de ruta)
text	string	Sí	Text de difusió (sense HTML)

Exemple

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Resposta

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

---

Eliminar credencial

Elimina una credencial. No pot tenir atorgaments associats.

DELETE /badges/{badgeId}

Exemple

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

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

Errors

• 400 — la credencial té atorgaments i no es pot eliminar
• 404 — credencial no trobada