Emettere Open Badges tramite l'API REST di Badges Ninja: guida rapida

La maggior parte dei programmi di certificazione non ha mai bisogno di un’API. Se gestisci un corso con qualche centinaio di diplomati all’anno, la dashboard fa tutto: progetti un badge nel designer visuale, carichi un CSV e ogni destinatario riceve una pagina di verifica e un certificato PDF. Se è il tuo caso, parti da come emettere Open Badges da un CSV e torna qui più tardi.

L’API si fa valere quando le credenziali devono essere emesse da un altro sistema: la tua piattaforma di apprendimento segna un corso come completato, il tuo strumento di iscrizione chiude un evento, il tuo sistema HR registra un modulo di compliance terminato. In questi casi nessuno vuole esportare un foglio di calcolo alla fine di ogni settimana. Una singola chiamata HTTP nel momento del completamento è più semplice, e il destinatario riceve il suo badge quando il traguardo è ancora fresco.

Questa guida rapida percorre l’intero tragitto in quattro chiamate: ottenere una chiave, creare un’emittente, creare un badge, assegnarlo. Poi vediamo come consegnare il link di verifica al destinatario e controllare il risultato. Ogni formato di richiesta qui sotto proviene dagli handler in produzione, quindi puoi copiarlo e lanciarlo.

Cosa ti serve prima di iniziare

• Un account gratuito su badges.ninja. Il piano Free basta per questo tutorial: include 2 emittenti, 5 badge, 2 postazioni e 1 chiave API.
• Una chiave API, creata dalla dashboard.
• Un PNG o JPG per l’immagine del badge, oppure un badge che hai progettato nel designer visuale.

L’URL di base per tutto è https://api.badges.ninja.

Passo 1: crea una chiave API

Accedi, apri API Keys nella barra laterale e fai clic su Create API Key. Dalle un nome che dica dove vivrà, per esempio “LMS integration”, così potrai distinguere le chiavi quando le ruoterai più avanti.

La chiave viene mostrata una sola volta. Copiala subito nel tuo gestore di segreti o in una variabile d’ambiente. Le chiavi hanno la forma bws_ seguita da 32 caratteri esadecimali e si inviano in un header X-Api-Key a ogni richiesta. Revocare una chiave dalla stessa schermata ha effetto immediato.

Qualche abitudine che ti evita problemi più avanti:

• Non mettere mai la chiave nel codice front-end o in un repository pubblico. Chiama l’API da un server, da una funzione serverless o da uno strumento di automazione.
• Usa una chiave per ogni integrazione. Se una viene compromessa, revochi una sola integrazione invece di tutte.
• La dashboard accetta anche la tua sessione autenticata (un JWT di Cognito inviato come Authorization: Bearer), ma per script e integrazioni lo strumento giusto è la chiave API.

Tutti gli esempi qui sotto leggono la chiave da una variabile d’ambiente chiamata BADGES_API_KEY.

Passo 2: crea un’emittente

Un’emittente è l’organizzazione che garantisce per il badge. Compare in ogni pagina di verifica e nei dati Open Badge v2.0, quindi usa il nome che le persone conoscono davvero.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

I campi obbligatori sono name (almeno 3 caratteri), url (un indirizzo http o https valido) ed email. I campi facoltativi sono logo (un’immagine codificata in base64) e linkedinOrganizationId, che attiva il pulsante Add to LinkedIn Profile sulle tue pagine pubbliche delle credenziali.

La risposta contiene l’identificatore dell’emittente:

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

Conserva quel valore esattamente com’è stato restituito. È l’input del passo successivo.

Verifica dell’emittente

I badge si possono creare solo sotto un’emittente verificata. La verifica funziona così:

• Se l’email dell’emittente coincide con quella del tuo account, l’emittente viene verificata automaticamente. È la via più rapida per un primo test.
• Se l’email è diversa, a quell’indirizzo arriva un’email di verifica con un codice. Confermi il codice nella dashboard (o tramite l’API delle emittenti) prima di creare i badge.

Quindi, per questo tutorial, usa la stessa email con cui ti sei registrato.

Passo 3: crea un badge

Un badge è il modello riutilizzabile: nome, descrizione, criteri e immagine. Ogni assegnazione che emetterai in seguito rimanda a esso.

La richiesta è JSON semplice. L’immagine viene inviata come stringa base64, quindi non c’è nessun upload multipart con cui litigare. Un prefisso data URL come data:image/png;base64, è accettato e rimosso.

JavaScript (Node 18 o successivo):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Tutti e cinque i campi (name, description, criteria, image, issuerId) sono obbligatori. Vale la pena conoscerne due facoltativi: shareText, il testo predefinito che i destinatari vedono quando condividono sui social (supporta i segnaposto {{badge_name}}, {{issuer_name}} e {{award_url}}), e designJson, che salva un documento del designer visuale così il badge potrà essere modificato livello per livello in seguito.

Un successo restituisce HTTP 200 con { "badgeId": "<id>" }. L’immagine viene archiviata in modo permanente e il badge è ora una BadgeClass Open Badge v2.0 che chiunque può recuperare.

Ha senso creare i badge nel codice?

Di solito no. Progettare un badge è un compito creativo, e il designer visuale (oltre 80 modelli, forme, icone, 11 font e caricamenti personalizzati) è un posto molto migliore di uno script. Uno schema comune è progettare ogni badge una volta nella dashboard e far sì che la tua integrazione emetta soltanto assegnazioni su di esso. Puoi elencare i tuoi badge con GET /badges e copiare l’id di quello che ti serve.

Crea i badge tramite l’API quando li generi in modo programmatico, per esempio uno per ogni corso in un catalogo di centinaia, o quando prepari un ambiente di test.

Passo 4: assegna il badge

È la chiamata che la tua integrazione farà migliaia di volte. Invia il badge, il destinatario e la data.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Le regole su cui si inciampa più spesso:

• recipient è un oggetto annidato con name ed email. Campi piatti come recipientEmail vengono rifiutati.
• recipient.name deve avere almeno 5 caratteri.
• issuedOn è obbligatorio. Invia i millisecondi epoch o una data ISO come 2026-09-28.
• expires è facoltativo e accetta gli stessi formati.

Un successo è HTTP 200 con un corpo che contiene l’awardId. L’email del destinatario è archiviata come hash SHA-256 nei dati Open Badge, quindi il JSON pubblico non la espone mai.

Passo 5: trova la pagina di verifica e il JSON Open Badge

La risposta dell’assegnazione ti dà un identificatore, non un link già pronto. L’identificatore termina con un GUID, e le pagine pubbliche si costruiscono a partire da quel GUID:

• Pagina di verifica leggibile da una persona: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Se il tuo awardId torna come URL completo, usa l’ultimo segmento del percorso come GUID.

Entrambe sono pubbliche. Chiunque abbia il link può verificare la credenziale senza creare un account, ed è proprio questo il punto: un datore di lavoro o un responsabile delle ammissioni dovrebbe poter controllare un badge in dieci secondi.

Recupera il JSON per vedere ciò che vede il mondo:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Ottieni un’Assertion Open Badge v2.0: il badge a cui rimanda, l’identità hashata del destinatario, la data di emissione e un blocco di verifica che punta all’assertion ospitata. Trattandosi di dati Open Badges standard, qualsiasi strumento che comprenda il formato può leggerli. Questa portabilità è il motivo per scegliere Open Badges invece di un PDF proprietario; Open Badges vs PDF certificates approfondisce il confronto.

Come i destinatari ricevono la credenziale

Creare un’assegnazione è una cosa distinta dall’avvisare il destinatario. I destinatari possono aprire le loro credenziali attraverso il portale destinatari su badges.ninja/me, che usa l’accesso con magic link senza password, e possono pubblicare un profilo pubblico su badges.ninja/u/<handle>. Dalla pagina di verifica possono aggiungere il badge a LinkedIn, scaricare il certificato PDF o condividere il link.

Per i primi test, assegna un badge a te stesso con il tuo indirizzo email e percorri l’esperienza del destinatario. È il modo più veloce per accorgerti di cose come una descrizione del badge che suona goffa.

Gestione degli errori senza dolore

L’API usa normali codici di stato HTTP. Quelli che incontrerai:

Due consigli pratici. Primo: tratta il 400 come un problema di dati e registra il corpo della risposta, perché indica il campo che non va. Secondo: rendi la tua integrazione idempotente dal tuo lato: salva l’awardId accanto al record di completamento nel tuo database e controllalo prima di richiamare l’API. In questo modo un webhook ripetuto o un job rilanciato non emetterà mai due credenziali alla stessa persona.

Mettere tutto insieme in un’integrazione reale

Un collegamento tipico si presenta così:

1. Progetta i badge nella dashboard, uno per corso o traguardo, e annota l’ID di ciascun badge.
2. Salva nel tuo sistema una mappatura da corso a ID del badge.
3. Quando un discente completa un corso, il tuo server chiama POST /awards con il suo nome, la sua email e la data di completamento.
4. Salva l’awardId restituito nel record di completamento.
5. Mostra il link di verifica dentro il tuo prodotto, così il discente lo vede senza uscirne.

Se preferisci non scrivere codice, la stessa chiamata funziona da qualsiasi strumento di automazione in grado di inviare una richiesta HTTP con un corpo JSON e un header personalizzato. Puntalo a https://api.badges.ninja/awards e mappa i campi del tuo modulo o foglio di calcolo su badgeId, recipient.name, recipient.email e issuedOn.

Piani e limiti da conoscere

L’API è disponibile su ogni piano; non paghi nulla in più per sbloccarla. Il piano Free ($0) copre 2 emittenti, 5 badge, 2 postazioni, 1 chiave API e 1.200 credenziali all’anno. Starter costa $9 al mese e Pro $29 al mese, con limiti più alti. Consulta la pagina dei prezzi per i numeri aggiornati prima di dimensionare un rollout. Se stai confrontando quanto fanno pagare le altre piattaforme per l’accesso all’API, Credly alternative mette i costi uno accanto all’altro.

Dove andare ora

• Il riferimento completo degli endpoint si trova nella documentazione dell’API, disponibile in 40 lingue.
• Per i dettagli su autenticazione e gestione delle chiavi, vedi la guida all’autenticazione.
• Per i codici di errore in dettaglio, vedi il riferimento degli errori.
• Quando una chiamata alla volta non basta più, usa le assegnazioni in blocco nella dashboard: carica un CSV e metti in pausa o riprendi l’esecuzione quando serve.

La parte difficile è il primo award riuscito. Dopo, il resto è collegare la stessa chiamata ai punti in cui i traguardi vengono già registrati.

Pronto a emettere la tua prima credenziale verificabile? Inizia gratis su badges.ninja — designer visuale, pagina di verifica pubblica, certificato PDF, output Open Badge v2.0. Nessuna carta di credito richiesta.