API delle credenziali

Gestisci i modelli di credenziale — quelli che consegni ai destinatari.

Tutti gli endpoint richiedono autenticazione tramite l'intestazione X-Api-Key. Consulta Autenticazione.

Creare una credenziale

Crea una nuova credenziale sotto un emittente verificato.

POST /badges

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Titolo della credenziale
description	string	Sì	Cosa rappresenta la credenziale
criteria	string	Sì	Cosa ha fatto il destinatario per conseguirla
image	string	Sì	Immagine codificata in Base64 (PNG o JPG)
issuerId	string	Sì	L'ID dell'emittente verificato

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

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

Note

• L'emittente deve essere verificato prima di creare credenziali.
• L'immagine viene caricata su IPFS per un'archiviazione perenne.

---

Elencare le credenziali

Recupera tutte le credenziali che hai creato.

GET /badges

Esempio

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

Risposta

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

---

Aggiornare una credenziale

Aggiorna una credenziale esistente. Cambiano soltanto i campi che invii.

PUT /badges/{badgeId}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID della credenziale (parametro di percorso)
name	string	No	Nuovo titolo
description	string	No	Nuova descrizione
criteria	string	No	Nuovi criteri
image	string	No	Nuova immagine in Base64

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

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

---

Aggiornare il testo di condivisione

Imposta il testo personalizzato mostrato ai destinatari al momento della condivisione sui social.

PUT /badges/{badgeId}/share-text

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
badgeId	string	Sì	L'ID della credenziale (parametro di percorso)
text	string	Sì	Testo di condivisione (senza HTML)

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

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

---

Eliminare una credenziale

Elimina una credenziale. Non deve avere rilasci associati.

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

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

Errori

• 400 — la credenziale ha rilasci e non può essere eliminata
• 404 — credenziale non trovata