Com emetre Open Badges des d'un CSV en menys de 5 minuts

Si alguna vegada has emès credencials a una cohort d’un destinatari en un destinatari, ja coneixes el problema: no escala més enllà d’una desena de persones abans de convertir-se en una tarda sencera de copiar i enganxar noms i correus. Una cohort de bootcamp de 40 persones, una llista d’assistents a un congrés de 500 persones o un desplegament de formació corporativa de 5.000 persones necessiten totes el mateix: puja una llista, tria una insígnia, fes clic a Emet i marxa.

Això és exactament el que fa Bulk Credentials a https://badges.ninja. Aquest recorregut cobreix tot el flux: preparar el teu CSV, configurar el lot, veure com s’executa i gestionar els casos desordenats del món real: una fila de destinatari amb una errada, un lot que s’interromp a mitja execució, o un programa que vol emetre de la mateixa manera des dels seus propis sistemes en lloc del tauler.

Abans de començar: què necessites

Dues coses, que segurament ja tens:

1. Una insígnia — dissenyada un cop al dissenyador visual i reutilitzada per a cada destinatari del lot. Si encara no n’has creat cap, consulta la nostra guia sobre com dissenyar el teu primer certificat verificable.
2. Un CSV de destinataris — nom, correu electrònic i (opcionalment) una data d’emissió. Aquest és tot l’esquema.

No necessites un compte d’emissor per destinatari, ni un servidor de correu, ni cap codi. Tot el que hi ha en aquesta secció passa al tauler.

Pas 1: prepara el teu CSV

El format de la llista de destinataris és deliberadament mínim:

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 — obligatori. Omple el camp de destinatari a l’assertion i al certificat.
• email — obligatori. Això es converteix en la identitat del destinatari a l’assertion de l’Open Badge v2.0: es xifra amb un hash amb una sal per credencial abans d’emmagatzemar-se, mai no es conserva en text pla.
• issued_on — opcional. Deixa’l en blanc i el lot utilitzarà el moment en què es processa cada fila; estableix-lo explícitament si estàs emplenant retroactivament una cohort que en realitat va acabar el mes passat.

La majoria de propietaris de programa exporten això directament d’allà on ja fan el seguiment de les finalitzacions: Airtable, Google Sheets, un full de càlcul lliurat per un instructor o un CSV extret del quadern de qualificacions d’un LMS. No cal cap eina d’exportació especial; qualsevol CSV amb aquestes tres columnes funciona.

Paranys habituals del CSV (i com els detecta la previsualització)

Un grapat de problemes apareixen constantment a les llistes de destinataris del món real, normalment perquè el CSV s’ha muntat combinant dos o tres fulls d’origen:

• Espais en blanc al final de les adreces de correu — una còpia enganxada des d’una llista en PDF o una exportació de Google Form sovint arrossega un espai invisible. Sembla correcte en una cel·la de full de càlcul, però falla la validació del correu en pujar-lo.
• Files duplicades — el mateix destinatari apareix dos cops perquè una llista de la cohort i una llista d’inscrits tardans s’han concatenat sense deduplicació.
• Formats de data inconsistents — una columna de 2026-07-01 barrejada amb 07/01/2026 d’una exportació diferent. Mantén-te a l’ISO 8601 (YYYY-MM-DD) i això desapareix del tot.
• Discrepàncies de majúscules i minúscules a les capçaleres — Email vs. email vs. E-mail. L’analitzador és tolerant amb les variants habituals, però un nom de capçalera totalment personalitzat no es mapejarà automàticament.

Cap d’aquests no és fatal: el pas de previsualització (a sota) fa aflorar cadascun abans que s’emeti res, de manera que la solució és «edita el full de càlcul, torna a pujar-lo» en lloc de «esbrina quin dels 3.000 destinataris ha rebut una insígnia trencada».

Pas 2: configura el lot

Des del tauler, obre Credentials → Bulk Credentials i tria la insígnia que estàs emetent. Aquest és el pas on estableixes tot allò que s’aplica a tot el lot: la insígnia mateixa, una data d’emissió compartida si no poses dates per fila al CSV i (si el teu perfil d’emissor en té un) l’ID d’organització de LinkedIn que permetrà a cada destinatari afegir la credencial al seu perfil amb un sol clic.

Aquest és un bon moment per comprovar dues vegades que la insígnia que has seleccionat és la versió definitiva: els destinataris veuran la imatge i els criteris que hi hagi adjuntats en el moment que emetis, no els que hi actualitzis més endavant.

Pas 3: puja i previsualitza

Deixa anar el teu CSV a dins i la plataforma l’analitza, et mostra una taula de previsualització i marca tot allò que no pot processar: un correu que falta, una data mal formada, una fila duplicada. No s’emet res fins que confirmes la previsualització.

Aquest pas de previsualització importa més del que sembla. Una errada en una fila d’un CSV de 2.000 files és fàcil de passar per alt a ull, i és molt més barat detectar-la abans que 1.999 files correctes ja s’hagin emès que no pas intentar desfer-ho després. Corregeix les files marcades al teu full de càlcul, torna a pujar-lo i la previsualització s’actualitza.

Pas 4: executa el lot

Prem Emet i el lot comença a processar-se. Una barra de progrés fa el seguiment de les files completades vs. les restants, i el lot s’executa al costat del servidor: no cal que mantinguis la pestanya oberta, i tancar el portàtil a mig lot no et fa perdre el punt on eres.

Aquesta última part val la pena detallar-la perquè és el detall que realment importa per a les cohorts grans: l’estat del lot viu al servidor, no al teu navegador. Si se’t cau la connexió, el portàtil s’adorm o simplement tanques la pestanya perquè comença una reunió, el lot continua executant-se (o es reprèn exactament on ho havia deixat si l’has posat en pausa) en lloc de tornar a començar de zero. Per a una cohort de bootcamp de 40 persones això és un extra agradable. Per a un desplegament corporatiu de 5.000 files, és la diferència entre «simplement funciona» i «algú ha de vigilar una pestanya del navegador durant vint minuts».

També pots posar en pausa deliberadament un lot en execució —posem que algú avisa que el text de criteris de la insígnia necessita un retoc a mitja execució de 3.000 files—, corregir el problema i reprendre sense tornar a emetre les files ja completades.

Pas 5: gestiona els errors

Les llistes de destinataris reals tenen files dolentes: un domini de correu amb una errada, un camp de nom que en realitat és buit, una entrada duplicada de dos fulls exportats que s’han combinat. Quan una fila falla, el lot no s’atura: continua processant la resta i marca l’error perquè el revisis després. Obtens una exportació de resultats que mostra exactament quines files han tingut èxit i quines no, de manera que pots corregir només les files que han fallat i executar un petit lot de seguiment en lloc de tornar a revisar tota la llista.

Això importa per al costum d’exportar CSV que ja és habitual al tauler de credencials: pots extreure un CSV del que realment s’ha emès en qualsevol moment, contrastar-lo amb la teva llista d’origen i saber amb precisió qui encara necessita una insígnia.

La via de l’API: mateix flux, sense tauler

Tot l’anterior dona per fet que hi ha algú assegut al tauler fent clics pel wizard. Si les teves finalitzacions ja viuen en un sistema —un LMS, un CRM, una automatització de full de càlcul—, pots controlar el mateix flux de credencials massives directament des de l’API d’Awards.

Una crida d’emissió mínima per destinatari té aquest aspecte:

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

O en Python, iterant sobre les files llegides del mateix CSV que altrament pujaries a mà:

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,
            },
        )

Val la pena recórrer a això quan l’emissió de credencials es desencadena per una altra cosa completament diferent —un webhook de finalització de curs, un canvi d’etapa al CRM, l’enviament d’un formulari— en lloc d’una persona que exporta un CSV manualment. Cobrim l’autenticació i la forma completa de la petició/resposta a la guia ràpida de l’API. Cada credencial creada d’aquesta manera és idèntica a una creada a través del wizard del tauler: la mateixa assertion d’Open Badge v2.0, la mateixa URL de verificació, el mateix certificat en PDF.

Wizard del tauler vs. API: quin vols realment?

La majoria d’equips comencen amb el wizard del tauler perquè no requereix res més que un CSV, i només passen a l’API un cop el mateix lot s’ha executat manualment tres o quatre vegades i el patró clarament val la pena automatitzar-lo.

Privadesa: què s’emmagatzema realment

Un CSV de noms i correus és informació personal, i val la pena saber què li passa després de pujar-lo. L’adreça de correu del destinatari no s’emmagatzema mai en text pla a la credencial mateixa: es xifra amb un hash amb una sal per credencial com a part de l’assertion d’Open Badge v2.0, seguint el format d’identitat de destinatari hashed de l’especificació. Aquest hash és el que un verificador comprova, no l’adreça en brut. El camp de nom s’emmagatzema tal com s’ha introduït, ja que està pensat per ser visible al certificat i a la pàgina de verificació. Si una fila necessita correcció després de l’emissió —un nom mal escrit, el cas més habitual—, pots editar o revocar la credencial individual des del tauler de credencials sense tocar la resta del lot.

Després del lot: notifica els destinataris

Emetre la insígnia i informar-ne el destinatari són dos passos diferents. Si el teu CSV no desencadena ja un correu a través del teu propi sistema, el flux de compartició massiva del tauler et permet seleccionar de manera múltiple les credencials que acabes de crear i enviar un correu de compartició personalitzat a tots ells d’una sola passada; consulta l’enviament massiu de correus de compartició per al recorregut complet, incloent-hi com se substitueix automàticament la personalització per destinatari (nom, imatge de la insígnia, enllaç de verificació).

Quan Bulk Credentials és l’eina adequada

L’emissió massiva és l’opció encertada sempre que el marc de «lot» encaixi amb el món real: una cohort que ha acabat el mateix dia, un congrés que tot just s’ha acabat, un desplegament de formació que arriba a una data límit de compliment. Si, en canvi, emets credencials puntuals a mesura que s’assoleixen fites individuals —un únic ascens, la finalització d’un únic projecte—, el formulari de credencial única és més ràpid que muntar un CSV d’una sola fila.

Per a qualsevol cosa recurrent —el mateix curs que s’executa cada mes, un procés d’incorporació continu—, la via de l’API de dalt val la pena configurar-la un cop. Converteix «executa credencials massives manualment cada cohort» en «les finalitzacions ja emeten credencials automàticament», que és la versió d’aquest flux de treball que la majoria de propietaris de programa realment volen després del segon o tercer lot manual.

A punt per emetre la teva primera credencial verificable? Comença gratis a badges.ninja: dissenyador visual, pàgina de verificació pública, certificat en PDF, sortida en Open Badge v2.0. No cal targeta de crèdit.