Referència de l'API d'insígnies: crea, verifica i obtén insígnies

Gestiona les plantilles d'insígnies: les credencials que emets als destinataris.

Per emetre aquesta insígnia a molts destinataris alhora mitjançant la càrrega d'un CSV en lloc de l'API, consulta Credencials en massa.

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

Crear una insígnia

Crea una insígnia nova sota un emissor verificat.

POST /badges

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
name	string	Sí	Títol de la insígnia
description	string	Sí	Què representa la insígnia
criteria	string	Sí	Què ha fet el destinatari per aconseguir aquesta insígnia
image	string	Sí	Imatge codificada en Base64 (PNG o JPG)
issuerId	string	Sí	L'ID de l'emissor verificat
shareText	string	No	Text per defecte per compartir a les xarxes socials per a aquesta insígnia. Admet els marcadors , i . Si s'omet, s'utilitza un text per defecte integrat.
designJson	string	No	Document serialitzat del dissenyador d'insígnies, desat perquè la insígnia es pugui tornar a editar capa per capa més endavant.

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

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

Notes

• L'emissor ha d'estar verificat abans de crear insígnies.
• La imatge es desa a Amazon S3 i es serveix mitjançant la nostra CDN global sota un URL immutable adreçat per contingut.
• Quan ja existeix una classe d'insígnia, emet-la als destinataris amb l'API de credencials.

---

Llistar insígnies

Obtén totes les insígnies que has creat.

GET /badges

Exemple

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

Resposta

[
  {
    "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://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Obtenir una insígnia

Obtén una sola insígnia, amb el seu text per compartir i el document serialitzat del dissenyador d'insígnies (designJson). Aquest és l'endpoint que utilitza el modal d'edició d'insígnies per recuperar cada capa; l'endpoint de llistat omet designJson per mantenir les respostes lleugeres.

GET /badges/{badgeId}

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la insígnia (paràmetre de ruta)

Exemple

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

Resposta

{
  "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://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

El text per compartir sempre s'inclou. La variant lleugera de llistat GET /badges?badgeId={id} retorna el mateix document sense designJson, i només inclou el text per compartir quan es crida amb includeShareText=true.

---

Actualitzar una insígnia

Actualitza una insígnia existent. Només es canvien els camps que indiquis.

PUT /badges/{badgeId}

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la insígnia (paràmetre de ruta)
name	string	No	Nou títol de la insígnia
description	string	No	Nova descripció
criteria	string	No	Nous criteris
image	string	No	Nova imatge codificada en Base64
designJson	string	No	Nou document serialitzat del dissenyador d'insígnies.

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

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

---

Actualitzar el text per compartir

Defineix el text personalitzat que es mostra quan els destinataris comparteixen aquesta insígnia a les xarxes socials.

PUT /badges/{badgeId}/share-text

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la insígnia (paràmetre de ruta)
text	string	Sí	Text per compartir (no es permet 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

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Eliminar una insígnia

Elimina una insígnia. La insígnia no pot tenir cap credencial.

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

Retorna una cadena de confirmació simple:

"badge has been deleted"

Errors

• 400 — la insígnia encara té credencials emeses: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — insígnia no trobada