Emet insígnies Open Badges amb l'API REST de Badges Ninja: guia d'inici ràpid

La majoria de programes de credencials no necessiten mai una API. Si portes un curs amb unes quantes centenes de graduats l’any, el tauler ho fa tot: dissenyes una insígnia al dissenyador visual, puges un CSV i cada destinatari rep una pàgina de verificació i un certificat en PDF. Si aquest és el teu cas, comença amb com emetre Open Badges des d’un CSV i torna més endavant.

L’API es guanya el lloc quan les credencials les ha d’emetre un altre sistema: la teva plataforma d’aprenentatge marca un curs com a completat, la teva eina d’inscripcions tanca un esdeveniment, el teu sistema de RH registra un mòdul de compliment normatiu acabat. En aquests casos ningú vol exportar un full de càlcul cada final de setmana. Una sola crida HTTP en el moment de la finalització és més senzilla, i el destinatari rep la insígnia mentre l’assoliment encara és fresc.

Aquesta guia d’inici ràpid recorre tot el camí en quatre crides: obtenir una clau, crear un emissor, crear una insígnia i atorgar-la. Després veiem com fer arribar l’enllaç de verificació al destinatari i com comprovar el resultat. Cada format de petició d’aquí sota prové dels handlers desplegats, així que pots copiar-lo i executar-lo.

Què necessites abans de començar

• Un compte gratuït a badges.ninja. El pla Free n’hi ha prou per a aquest tutorial: inclou 2 emissors, 5 insígnies, 2 seients i 1 clau d’API.
• Una clau d’API, creada des del tauler.
• Un PNG o JPG per a la imatge de la insígnia, o una insígnia dissenyada al dissenyador visual.

L’URL base per a tot és https://api.badges.ninja.

Pas 1: crea una clau d’API

Inicia sessió, obre API Keys a la barra lateral i fes clic a Create API Key. Posa-li un nom que digui on viurà, com ara «Integració LMS», per poder distingir les claus quan les rotis més endavant.

La clau es mostra una sola vegada. Copia-la tot seguit al teu gestor de secrets o a una variable d’entorn. Les claus tenen la forma bws_ seguida de 32 caràcters hexadecimals, i les envies en una capçalera X-Api-Key a cada petició. Revocar una clau des de la mateixa pantalla té efecte immediat.

Uns quants hàbits que t’estalvien problemes més endavant:

• No posis mai la clau en codi de front-end ni en un repositori públic. Crida l’API des d’un servidor, una funció serverless o una eina d’automatització.
• Fes servir una clau per integració. Si una es filtra, revoques una sola integració i no totes.
• El tauler també accepta la teva sessió iniciada (un JWT de Cognito enviat com a Authorization: Bearer), però per a scripts i integracions la clau d’API és l’eina adequada.

Tots els exemples d’aquí sota llegeixen la clau d’una variable d’entorn anomenada BADGES_API_KEY.

Pas 2: crea un emissor

Un emissor és l’organització que avala la insígnia. Apareix a cada pàgina de verificació i dins de les dades Open Badge v2.0, així que fes servir el nom que la gent coneix de debò.

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

Els camps obligatoris són name (almenys 3 caràcters), url (una adreça http o https vàlida) i email. Els camps opcionals són logo (una imatge codificada en base64) i linkedinOrganizationId, que activa el botó Add to LinkedIn Profile a les pàgines públiques de les teves credencials.

La resposta conté l’identificador de l’emissor:

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

Conserva aquest valor exactament tal com es retorna. És l’entrada del pas següent.

Verificació de l’emissor

Només es poden crear insígnies sota un emissor verificat. La verificació funciona així:

• Si el correu de l’emissor coincideix amb el correu del teu compte, l’emissor es verifica automàticament. És el camí més ràpid per a una primera prova.
• Si el correu és diferent, s’envia a aquesta adreça un correu de verificació amb un codi. Has de confirmar el codi al tauler (o mitjançant l’API d’emissors) abans de crear insígnies.

Per tant, per a aquest tutorial fes servir el mateix correu amb què t’has registrat.

Pas 3: crea una insígnia

Una insígnia és la plantilla reutilitzable: nom, descripció, criteris i imatge. Cada atorgament que emetis després hi apunta.

La petició és JSON pla. La imatge s’hi envia com a cadena base64, així que no cal lluitar amb càrregues multipart. Un prefix de data URL com data:image/png;base64, s’accepta i s’elimina.

JavaScript (Node 18 o posterior):

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)

Els cinc camps (name, description, criteria, image, issuerId) són obligatoris. N’hi ha dos d’opcionals que val la pena conèixer: shareText, el text per defecte que veuen els destinataris quan comparteixen a les xarxes socials (admet els marcadors {{badge_name}}, {{issuer_name}} i {{award_url}}), i designJson, que desa un document del dissenyador visual perquè la insígnia es pugui editar capa per capa més endavant.

Un èxit retorna HTTP 200 amb { "badgeId": "<id>" }. La imatge es desa de manera permanent, i la insígnia ja és una BadgeClass Open Badge v2.0 que qualsevol pot consultar.

Cal crear insígnies per codi?

Normalment no. El disseny d’una insígnia és una tasca creativa, i el dissenyador visual (més de 80 plantilles, formes, icones, 11 tipografies i càrregues personalitzades) és un lloc molt millor que un script. Un patró habitual és dissenyar cada insígnia una vegada al tauler i que la teva integració només emeti atorgaments contra ella. Pots llistar les insígnies amb GET /badges i copiar l’id de la que vulguis.

Crea insígnies per l’API quan les generis programàticament, per exemple una per curs en un catàleg de centenars, o quan estiguis poblant un entorn de proves.

Pas 4: atorga la insígnia

Aquesta és la crida que la teva integració farà milers de vegades. Envia la insígnia, el destinatari i 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"]

Les regles que fan ensopegar la gent:

• recipient és un objecte niat amb name i email. Els camps plans com recipientEmail es rebutgen.
• recipient.name ha de tenir almenys 5 caràcters.
• issuedOn és obligatori. Envia mil·lisegons d’època o una cadena de data ISO com 2026-09-28.
• expires és opcional i accepta els mateixos formats.

Un èxit és un HTTP 200 amb un cos que conté l’awardId. El correu del destinatari es desa com a hash SHA-256 a les dades Open Badge, de manera que el JSON públic no l’exposa mai.

Pas 5: troba la pàgina de verificació i el JSON Open Badge

La resposta de l’atorgament et dona un identificador, no un enllaç llest per fer servir. L’identificador acaba en un GUID, i les pàgines públiques es construeixen a partir d’aquest GUID:

• Pàgina de verificació llegible: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Si el teu awardId torna com una URL completa, fes servir l’últim segment del camí com a GUID.

Les dues són públiques. Qualsevol persona amb l’enllaç pot verificar la credencial sense crear un compte, i aquest és el punt: un empresari o un responsable d’admissions ha de poder comprovar una insígnia en deu segons.

Obtén el JSON per veure què veu el món:

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

Obtens una asserció Open Badge v2.0: la insígnia a la qual fa referència, la identitat hashejada del destinatari, la data d’emissió i un bloc de verificació que apunta a l’asserció allotjada. Com que són dades estàndard d’Open Badges, qualsevol eina que entengui el format les pot llegir. Aquesta portabilitat és el motiu per triar Open Badges abans que un PDF propietari; Open Badges vs certificats en PDF aprofundeix en el balanç.

Com reben la credencial els destinataris

Crear un atorgament és una cosa diferent d’avisar el destinatari. Els destinataris poden obrir les seves credencials a través del portal de destinataris a badges.ninja/me, que fa servir inici de sessió amb enllaç màgic, sense contrasenya, i poden publicar un perfil públic a badges.ninja/u/<handle>. Des de la pàgina de verificació poden afegir la insígnia a LinkedIn, baixar el certificat en PDF o compartir l’enllaç.

Per a les primeres proves, envia’t un atorgament a tu mateix amb el teu correu i recorre l’experiència del destinatari. És la manera més ràpida de detectar coses com una descripció de la insígnia que sona estranya.

Gestió d’errors sense maldecaps

L’API fa servir codis d’estat HTTP ordinaris. Els que trobaràs:

Dos consells pràctics. Primer, tracta el 400 com un problema de dades i registra el cos de la resposta, ja que anomena el camp que falla. Segon, fes la teva integració idempotent de la teva banda: desa l’awardId al costat del registre de finalització a la teva base de dades i comprova’l abans de tornar a cridar l’API. Així un webhook reintentat o una tasca reexecutada no emetrà mai dues credencials a la mateixa persona.

Ajuntar-ho tot en una integració real

Un muntatge típic té aquest aspecte:

1. Dissenya les insígnies al tauler, una per curs o fita, i anota l’ID de cadascuna.
2. Desa al teu sistema una correspondència de curs a ID d’insígnia.
3. Quan un alumne completa un curs, el teu servidor crida POST /awards amb el seu nom, correu i data de finalització.
4. Desa l’awardId retornat al registre de finalització.
5. Mostra l’enllaç de verificació dins del teu propi producte, perquè l’alumne el vegi sense sortir-ne.

Si prefereixes no escriure codi, la mateixa crida funciona des de qualsevol eina d’automatització que pugui enviar una petició HTTP amb cos JSON i una capçalera personalitzada. Apunta-la a https://api.badges.ninja/awards i fes correspondre els camps del teu formulari o full de càlcul amb badgeId, recipient.name, recipient.email i issuedOn.

Plans i límits que convé conèixer

L’API està disponible a tots els plans; no pagues res extra per desbloquejar-la. El pla Free ($0) cobreix 2 emissors, 5 insígnies, 2 seients, 1 clau d’API i 1.200 credencials per any. Starter costa $9 al mes i Pro $29 al mes, amb límits més alts. Consulta la pàgina de preus per veure les xifres actuals abans de dimensionar un desplegament. Si compares el que cobren altres plataformes per l’accés a l’API, Credly alternative exposa els costos costat per costat.

On anar després

• La referència completa dels endpoints és a la documentació de l’API, disponible en 40 idiomes.
• Per als detalls d’autenticació i la gestió de claus, consulta la guia d’autenticació.
• Per als codis d’error en profunditat, consulta la referència d’errors.
• Quan et quedi petit fer una crida cada vegada, fes servir els atorgaments massius al tauler: puja un CSV i pausa o reprèn l’execució si cal.

El primer atorgament reeixit és la part difícil. Després, només cal connectar la mateixa crida allà on els assoliments ja es registren.

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