Riferimento API dei badge: crea, verifica e recupera i badge

Gestisci i modelli di badge — le credenziali che emetti ai destinatari.

Per emettere questo badge a molti destinatari contemporaneamente tramite caricamento CSV anziché tramite API, vedi Credenziali in blocco.

Tutti gli endpoint richiedono l'autenticazione tramite l'header X-Api-Key. Vedi Autenticazione.

Crea badge

Crea un nuovo badge sotto un emittente verificato.

POST /badges

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Titolo del badge
description	string	Sì	Che cosa rappresenta il badge
criteria	string	Sì	Che cosa ha fatto il destinatario per ottenere questo badge
image	string	Sì	Immagine codificata in Base64 (PNG o JPG)
issuerId	string	Sì	L'ID dell'emittente verificato
shareText	string	No	Testo di condivisione social predefinito per questo badge. Supporta i segnaposto , e . Se omesso, usa un valore predefinito integrato.
designJson	string	No	Documento serializzato del designer di badge, memorizzato per poter modificare di nuovo il badge livello per livello in seguito.

Esempio

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"
    }
  }'

Risposta

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

Note

• L'emittente deve essere verificato prima di creare i badge.
• L'immagine viene archiviata su Amazon S3 e servita tramite la nostra CDN globale con un URL immutabile e indirizzato per contenuto (content-addressed).
• Una volta creata la classe di badge, emettila ai destinatari tramite l'API delle credenziali.

---

Elenca badge

Recupera tutti i badge che hai creato.

GET /badges

Esempio

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

Risposta

[
  {
    "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"
  }
]

---

Ottieni badge

Recupera un singolo badge, compresi il testo di condivisione e il documento serializzato del designer di badge (designJson). È l'endpoint che la finestra modale Modifica badge usa per ricostruire i singoli livelli; l'endpoint dell'elenco omette designJson per mantenere le risposte leggere.

GET /badges/{badgeId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID del badge (parametro di percorso)

Esempio

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

Risposta

{
  "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"
}

Il testo di condivisione è sempre incluso. La variante più leggera dell'elenco, GET /badges?badgeId={id}, restituisce lo stesso documento senza designJson e include il testo di condivisione solo se chiamata con includeShareText=true.

---

Aggiorna badge

Aggiorna un badge esistente. Vengono modificati solo i campi che fornisci.

PUT /badges/{badgeId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID del badge (parametro di percorso)
name	string	No	Nuovo titolo del badge
description	string	No	Nuova descrizione
criteria	string	No	Nuovi criteri
image	string	No	Nuova immagine codificata in Base64
designJson	string	No	Nuovo documento serializzato del designer di badge.

Esempio

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"
    }
  }'

Risposta

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

---

Aggiorna testo di condivisione

Imposta il testo personalizzato mostrato quando i destinatari condividono questo badge sui social media.

PUT /badges/{badgeId}/share-text

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID del badge (parametro di percorso)
text	string	Sì	Testo di condivisione (HTML non consentito)

Esempio

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:"
    }
  }'

Risposta

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

---

Elimina badge

Elimina un badge. Il badge non deve avere credenziali.

DELETE /badges/{badgeId}

Esempio

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

Risposta

Restituisce una semplice stringa di conferma:

"badge has been deleted"

Errori

• 400 — il badge ha ancora credenziali emesse: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — badge non trovato