Come emettere Open Badge da un CSV in meno di 5 minuti

Se ti è mai capitato di emettere credenziali a un gruppo un destinatario alla volta, conosci già il problema: non regge oltre le dieci persone circa prima di trasformarsi in un pomeriggio passato a copiare e incollare nomi ed email. Un gruppo di bootcamp da 40 persone, un elenco di 500 partecipanti a una conferenza o l’implementazione di una formazione aziendale per 5.000 persone hanno tutti bisogno della stessa cosa: caricare un elenco, scegliere un badge, cliccare Emetti e andartene.

Ed è esattamente ciò che fanno le Credenziali di massa su https://badges.ninja. Questa guida copre l’intero flusso: preparare il tuo CSV, configurare il lotto, guardarlo elaborare e gestire i casi complicati del mondo reale — una riga di un destinatario con un errore di battitura, un lotto interrotto a metà o un programma che vuole emettere alla stessa maniera dai propri sistemi invece che dalla dashboard.

Prima di iniziare: cosa ti serve

Due cose, entrambe che probabilmente hai già:

1. Un badge — progettato una volta nel designer visivo, riutilizzato per ogni destinatario del lotto. Se non ne hai ancora creato uno, consulta la nostra guida su come progettare il tuo primo certificato verificabile.
2. Un CSV di destinatari — nome, email e (facoltativamente) una data di emissione. Questo è tutto lo schema.

Non ti serve un account emittente per destinatario, un server di posta o alcun codice. Tutto in questa sezione avviene nella dashboard.

Passo 1: prepara il tuo CSV

Il formato dell’elenco dei destinatari è volutamente minimale:

name,email,issued_on
Maria Gonzalez,maria@example.com,2026-07-01
David Kim,david@example.com,2026-07-01
Priya Patel,priya@example.com,

• name — obbligatorio. Popola il campo destinatario sull’assertion e sul certificato.
• email — obbligatoria. Diventa l’identità del destinatario sull’assertion Open Badge v2.0 — sottoposta ad hashing con un salt per credenziale prima di essere archiviata, mai conservata in chiaro.
• issued_on — facoltativa. Lasciala vuota e il lotto usa il momento in cui ogni riga viene elaborata; impostala esplicitamente se stai recuperando un gruppo che in realtà ha finito il mese scorso.

La maggior parte dei responsabili di programma esporta questi dati direttamente da dove già tracciano i completamenti — Airtable, Google Sheets, un foglio di calcolo consegnato da un docente o un CSV estratto dal registro voti di un LMS. Non serve alcuno strumento di esportazione speciale; funziona qualsiasi CSV con queste tre colonne.

Trappole comuni dei CSV (e come l’anteprima le cattura)

Un pugno di problemi ricorre di continuo negli elenchi di destinatari del mondo reale, di solito perché il CSV è stato assemblato unendo due o tre fogli di origine:

• Spazi bianchi finali negli indirizzi email — un copia-incolla da un elenco PDF o da un’esportazione di Google Form spesso porta con sé uno spazio invisibile. Sembra a posto nella cella di un foglio di calcolo ma fallisce la validazione dell’email durante il caricamento.
• Righe duplicate — lo stesso destinatario che compare due volte perché un elenco del gruppo e un elenco di iscritti in ritardo sono stati concatenati senza deduplicazione.
• Formati di data incoerenti — una colonna di 2026-07-01 mescolata con 07/01/2026 da un’altra esportazione. Attieniti allo standard ISO 8601 (YYYY-MM-DD) e questo sparisce del tutto.
• Discrepanze di maiuscole nelle intestazioni — Email contro email contro E-mail. Il parser è tollerante verso le varianti comuni, ma un nome di intestazione completamente personalizzato non verrà mappato automaticamente.

Nessuno di questi è fatale — il passaggio di anteprima (sotto) fa emergere ciascuno di essi prima che venga emesso qualcosa, quindi la correzione è «modifica il foglio di calcolo, ricarica» invece di «capire quale dei 3.000 destinatari ha ricevuto un badge rotto».

Passo 2: configura il lotto

Dalla dashboard, apri Credenziali → Credenziali di massa e scegli il badge che stai emettendo. Questo è il passaggio in cui imposti tutto ciò che si applica all’intero lotto: il badge stesso, una data di emissione condivisa se non stai inserendo date per riga nel CSV e (se il tuo profilo emittente ne ha uno) l’ID dell’organizzazione LinkedIn che permetterà a ogni destinatario di aggiungere la credenziale al proprio profilo con un solo clic.

È un buon momento per ricontrollare che il badge selezionato sia la versione definitiva — i destinatari vedranno qualsiasi immagine e criterio siano associati a esso nel momento in cui emetti, non ciò che aggiorni in seguito.

Passo 3: carica e visualizza l’anteprima

Trascina dentro il tuo CSV e la piattaforma lo analizza, ti mostra una tabella di anteprima e segnala tutto ciò che non riesce a elaborare — un’email mancante, una data malformata, una riga duplicata. Non viene emesso nulla finché non confermi l’anteprima.

Questo passaggio di anteprima conta più di quanto sembri. Un errore di battitura in una riga di un CSV da 2.000 righe è facile da non notare a occhio, ed è molto più economico coglierlo prima che 1.999 righe corrette siano già state emesse piuttosto che cercare di rimediare dopo. Correggi le righe segnalate nel tuo foglio di calcolo, ricarica e l’anteprima si aggiorna.

Passo 4: avvia il lotto

Premi Emetti e il lotto inizia l’elaborazione. Una barra di avanzamento traccia le righe completate rispetto a quelle rimanenti, e il lotto viene eseguito lato server — non devi tenere la scheda aperta, e chiudere il portatile a metà lotto non fa perdere il punto in cui eri.

Vale la pena esplicitare quest’ultimo aspetto perché è il dettaglio che conta davvero per i grandi gruppi: lo stato del lotto vive sul server, non nel tuo browser. Se cade la connessione, il portatile va in sospensione o chiudi semplicemente la scheda perché inizia una riunione, il lotto continua a girare (o riprende esattamente da dove si era interrotto se l’hai messo in pausa) invece di ripartire da zero. Per un gruppo di bootcamp da 40 persone questo è un piacevole extra. Per un’implementazione aziendale da 5.000 righe, è la differenza tra «funziona e basta» e «qualcuno deve fare da babysitter a una scheda del browser per venti minuti».

Puoi anche mettere in pausa deliberatamente un lotto in esecuzione — poniamo, qualcuno segnala che il testo dei criteri del badge ha bisogno di una piccola modifica a metà di un’esecuzione da 3.000 righe — correggere il problema e riprendere senza riemettere le righe già completate.

Passo 5: gestisci gli errori

Gli elenchi di destinatari reali hanno righe cattive: un dominio email con un errore di battitura, un campo nome che in realtà è vuoto, una voce duplicata dovuta all’unione di due fogli esportati. Quando una riga fallisce, il lotto non si ferma — continua a elaborare il resto e segnala l’errore per una revisione successiva. Ottieni un’esportazione dei risultati che mostra esattamente quali righe sono andate a buon fine e quali no, così puoi correggere solo le righe fallite e rieseguire un piccolo lotto di seguito invece di ricontrollare l’intero elenco.

Questo è importante per l’abitudine all’esportazione CSV già comune nella dashboard delle credenziali — puoi estrarre in qualsiasi momento un CSV di ciò che è stato effettivamente emesso, incrociarlo con il tuo elenco di origine e sapere con precisione chi ha ancora bisogno di un badge.

Il percorso API: stesso flusso, nessuna dashboard

Tutto quanto sopra presuppone che qualcuno sia seduto alla dashboard a cliccare attraverso la procedura guidata. Se i tuoi completamenti vivono già in un sistema — un LMS, un CRM, un’automazione di fogli di calcolo — puoi guidare lo stesso flusso di credenziali di massa direttamente dall’API Awards.

Una chiamata minimale di emissione per destinatario ha questo aspetto:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{
    "badgeId": "badge_9f8e7d6c5b4a",
    "recipient": {
      "name": "Maria Gonzalez",
      "email": "maria@example.com"
    },
    "issuedOn": "2026-07-01T00:00:00Z"
  }'

Oppure in Python, iterando sulle righe lette dallo stesso CSV che altrimenti caricheresti a mano:

import csv
import requests

API_KEY = "bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
BADGE_ID = "badge_9f8e7d6c5b4a"

with open("recipients.csv") as f:
    for row in csv.DictReader(f):
        requests.post(
            "https://api.badges.ninja/awards",
            headers={"X-Api-Key": API_KEY},
            json={
                "badgeId": BADGE_ID,
                "recipient": {"name": row["name"], "email": row["email"]},
                "issuedOn": row.get("issued_on") or None,
            },
        )

Vale la pena ricorrervi quando l’emissione delle credenziali è attivata da qualcos’altro del tutto — un webhook di completamento corso, un cambio di fase nel CRM, l’invio di un modulo — invece che da una persona che esporta manualmente un CSV. Copriamo l’autenticazione e la struttura completa di richiesta/risposta nella guida rapida all’API. Ogni credenziale creata in questo modo è identica a una creata tramite la procedura guidata della dashboard: stessa assertion Open Badge v2.0, stesso URL di verifica, stesso certificato PDF.

Procedura guidata della dashboard vs. API: quale vuoi davvero?

La maggior parte dei team parte dalla procedura guidata della dashboard perché non richiede nulla oltre a un CSV, e passa all’API solo dopo che lo stesso lotto è stato eseguito manualmente tre o quattro volte e lo schema merita ovviamente di essere automatizzato.

Privacy: cosa viene effettivamente archiviato

Un CSV di nomi ed email è un dato personale, e vale la pena sapere cosa gli succede dopo il caricamento. L’indirizzo email del destinatario non viene mai archiviato in chiaro sulla credenziale stessa — è sottoposto ad hashing con un salt per credenziale come parte dell’assertion Open Badge v2.0, seguendo il formato di identità del destinatario hashed della specifica. È quell’hash ciò che un verificatore controlla, non l’indirizzo grezzo. Il campo nome viene archiviato così com’è inserito, poiché è pensato per essere visibile sul certificato e sulla pagina di verifica. Se una riga necessita di correzione dopo l’emissione — un nome scritto male, il caso più comune — puoi modificare o revocare la singola credenziale dalla dashboard delle credenziali senza toccare il resto del lotto.

Dopo il lotto: avvisa i destinatari

Emettere il badge e informarne il destinatario sono due passaggi diversi. Se il tuo CSV non attiva già un’email tramite il tuo sistema, il flusso di condivisione di massa della dashboard ti permette di selezionare più credenziali appena create e inviare a tutti loro un’email di condivisione personalizzata in un’unica passata — consulta l’invio di massa delle email di condivisione per la guida completa, incluso come la personalizzazione per destinatario (nome, immagine del badge, link di verifica) venga sostituita automaticamente.

Quando le Credenziali di massa sono lo strumento giusto

L’emissione di massa è la scelta giusta ogni volta che l’inquadramento «lotto» calza con il mondo reale: un gruppo che ha finito lo stesso giorno, una conferenza appena conclusa, un’implementazione formativa che deve rispettare una scadenza di conformità. Se invece stai emettendo credenziali occasionali man mano che vengono raggiunti singoli traguardi — una singola promozione, il completamento di un singolo progetto — il modulo per credenziale singola è più rapido dell’assemblare un CSV di una sola riga.

Per qualsiasi cosa ricorrente — lo stesso corso che gira ogni mese, una pipeline di onboarding continua — vale la pena configurare una volta il percorso API di cui sopra. Trasforma «esegui manualmente le credenziali di massa a ogni gruppo» in «i completamenti emettono già le credenziali automaticamente», che è la versione di questo flusso di lavoro che la maggior parte dei responsabili di programma vuole davvero dopo il secondo o terzo lotto manuale.

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