Emiterea de Open Badges prin API-ul REST Badges Ninja: ghid rapid

Majoritatea programelor de acreditare nu au nevoie de un API. Dacă organizezi un curs cu câteva sute de absolvenți pe an, panoul de control face totul: proiectezi o insignă digitală în designerul vizual, încarci un CSV, iar fiecare destinatar primește o pagină de verificare și un certificat PDF. Dacă ăsta e cazul tău, începe cu cum emiți Open Badges dintr-un CSV și revino mai târziu.

API-ul își merită locul atunci când acreditările trebuie emise de un alt sistem: platforma ta de învățare marchează un curs ca finalizat, instrumentul de înregistrare închide un eveniment, sistemul de HR înregistrează un modul de conformitate încheiat. În astfel de situații nimeni nu vrea să exporte o foaie de calcul la sfârșitul fiecărei săptămâni. Un singur apel HTTP în momentul finalizării e mai simplu, iar destinatarul primește insigna cât realizarea e încă proaspătă.

Acest ghid rapid parcurge tot drumul în patru apeluri: obții o cheie, creezi un emitent, creezi o insignă, o acorzi. Apoi vedem cum îi dai destinatarului linkul de verificare și cum verifici rezultatul. Fiecare formă de cerere de mai jos provine din handlerele deja implementate, deci o poți copia și rula.

De ce ai nevoie înainte să începi

• Un cont gratuit pe badges.ninja. Planul Free este suficient pentru acest tutorial: include 2 emitenți, 5 insigne, 2 locuri și 1 cheie API.
• O cheie API, creată din panoul de control.
• Un PNG sau JPG pentru imaginea insignei, sau o insignă proiectată în designerul vizual.

URL-ul de bază pentru tot este https://api.badges.ninja.

Pasul 1: Creează o cheie API

Autentifică-te, deschide API Keys în bara laterală și apasă Create API Key. Dă-i un nume care spune unde va fi folosită, de exemplu „LMS integration”, ca să poți distinge cheile când le vei roti mai târziu.

Cheia este afișată exact o dată. Copiaz-o imediat în managerul tău de secrete sau într-o variabilă de mediu. Cheile arată ca bws_ urmat de 32 de caractere hexazecimale și se trimit în antetul X-Api-Key la fiecare cerere. Revocarea unei chei din același ecran are efect imediat.

Câteva obiceiuri care te scutesc de probleme mai târziu:

• Nu pune niciodată cheia în codul front-end sau într-un depozit public. Apelează API-ul de pe un server, dintr-o funcție serverless sau dintr-un instrument de automatizare.
• Folosește o cheie pentru fiecare integrare. Dacă una se scurge, revoci o singură integrare, nu pe toate.
• Panoul de control acceptă și sesiunea ta autentificată (un JWT Cognito trimis ca Authorization: Bearer), dar pentru scripturi și integrări cheia API este instrumentul potrivit.

Toate exemplele de mai jos citesc cheia dintr-o variabilă de mediu numită BADGES_API_KEY.

Pasul 2: Creează un emitent

Un emitent este organizația care stă în spatele insignei. Apare pe fiecare pagină de verificare și în datele Open Badge v2.0, așa că folosește numele pe care oamenii îl cunosc cu adevărat.

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

Câmpurile obligatorii sunt name (cel puțin 3 caractere), url (o adresă http sau https validă) și email. Câmpurile opționale sunt logo (o imagine codificată base64) și linkedinOrganizationId, care activează butonul Add to LinkedIn Profile pe paginile tale publice de acreditări.

Răspunsul conține identificatorul emitentului:

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

Păstrează valoarea exact așa cum a fost returnată. Este intrarea pentru pasul următor.

Verificarea emitentului

Insignele pot fi create doar sub un emitent verificat. Verificarea funcționează astfel:

• Dacă emailul emitentului coincide cu emailul contului tău, emitentul este verificat automat. Este cea mai rapidă cale pentru un prim test.
• Dacă emailul este diferit, la acea adresă se trimite un email de verificare cu un cod. Confirmi codul în panoul de control (sau prin API-ul pentru emitenți) înainte de a crea insigne.

Așadar, pentru acest tutorial folosește același email cu care te-ai înregistrat.

Pasul 3: Creează o insignă

O insignă este șablonul reutilizabil: nume, descriere, criterii și imagine. Fiecare acordare pe care o emiți ulterior trimite înapoi la ea.

Cererea este JSON simplu. Imaginea se trimite ca șir base64, deci nu ai de luptat cu un upload multipart. Un prefix de tip data URL, precum data:image/png;base64,, este acceptat și eliminat.

JavaScript (Node 18 sau mai nou):

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)

Toate cele cinci câmpuri (name, description, criteria, image, issuerId) sunt obligatorii. Merită cunoscute două câmpuri opționale: shareText, textul implicit pe care destinatarii îl văd când distribuie pe rețelele sociale (acceptă substituenții {{badge_name}}, {{issuer_name}} și {{award_url}}), și designJson, care stochează un document din designerul vizual, astfel încât insigna să poată fi editată ulterior strat cu strat.

Un succes returnează HTTP 200 cu { "badgeId": "<id>" }. Imaginea este stocată permanent, iar insigna este acum un BadgeClass Open Badge v2.0 pe care îl poate obține oricine.

Ar trebui să creezi insigne în cod?

De obicei, nu. Designul unei insigne este o sarcină creativă, iar designerul vizual (peste 80 de șabloane, forme, pictograme, 11 fonturi și încărcări personalizate) este un loc mult mai potrivit pentru ea decât un script. Un tipar des întâlnit: proiectezi fiecare insignă o singură dată în panoul de control, apoi integrarea ta doar emite acordări pentru ea. Îți poți lista insignele cu GET /badges și poți copia id-ul celei dorite.

Creează insigne prin API când le generezi programatic, de exemplu una pentru fiecare curs dintr-un catalog de sute, sau când populezi un mediu de test.

Pasul 4: Acordă insigna

Acesta este apelul pe care integrarea ta îl va face de mii de ori. Trimite insigna, destinatarul și 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"]

Regulile la care se împiedică lumea:

• recipient este un obiect imbricat cu name și email. Câmpurile simple precum recipientEmail sunt respinse.
• recipient.name trebuie să aibă cel puțin 5 caractere.
• issuedOn este obligatoriu. Trimite milisecunde epoch sau un șir de dată ISO precum 2026-09-28.
• expires este opțional și acceptă aceleași formate.

Un succes înseamnă HTTP 200 cu un corp care conține awardId. Emailul destinatarului este stocat ca hash SHA-256 în datele Open Badge, deci JSON-ul public nu îl expune niciodată.

Pasul 5: Găsește pagina de verificare și JSON-ul Open Badge

Răspunsul la acordare îți oferă un identificator, nu un link gata făcut. Identificatorul se termină cu un GUID, iar paginile publice se construiesc din acest GUID:

• Pagina de verificare, ușor de citit: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Dacă awardId revine ca URL complet, folosește ultimul segment al căii drept GUID.

Ambele sunt publice. Oricine are linkul poate verifica acreditarea fără să-și creeze un cont, și tocmai asta e ideea: un angajator sau un responsabil de admitere ar trebui să poată verifica o insignă în zece secunde.

Obține JSON-ul ca să vezi ce vede lumea:

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

Primești o Assertion Open Badge v2.0: insigna la care face referire, identitatea hash-uită a destinatarului, data emiterii și un bloc de verificare care trimite înapoi la assertion-ul găzduit. Fiindcă sunt date standard Open Badges, orice instrument care înțelege formatul le poate citi. Această portabilitate este motivul pentru care alegi Open Badges în locul unui PDF proprietar; Open Badges vs PDF certificates analizează compromisul în detaliu.

Cum primesc destinatarii acreditarea

Crearea unei acordări este separată de anunțarea destinatarului. Destinatarii își pot deschide acreditările prin portalul pentru destinatari de la badges.ninja/me, care folosește autentificare cu magic link, fără parolă, și pot publica un profil public la badges.ninja/u/<handle>. Din pagina de verificare pot adăuga insigna pe LinkedIn, pot descărca certificatul PDF sau pot distribui linkul.

La primele teste, trimite-ți o acordare pe propria adresă de email și parcurge experiența destinatarului. E cea mai rapidă metodă de a observa lucruri precum o descriere a insignei care sună stângaci.

Gestionarea erorilor fără bătăi de cap

API-ul folosește coduri de stare HTTP obișnuite. Pe acestea le vei întâlni:

Două sfaturi practice. În primul rând, tratează 400 ca pe o problemă de date și loghează corpul răspunsului, deoarece numește câmpul care a eșuat. În al doilea rând, fă-ți integrarea idempotentă din partea ta: stochează awardId lângă înregistrarea finalizării în propria bază de date și verifică-l înainte de a apela din nou API-ul. Astfel, un webhook reîncercat sau un job rulat din nou nu va emite aceleiași persoane două acreditări.

Totul laolaltă într-o integrare reală

O conectare tipică arată așa:

1. Proiectezi insignele în panoul de control, una pentru fiecare curs sau etapă, și notezi ID-ul fiecărei insigne.
2. Stochezi în sistemul tău o corespondență între curs și ID-ul insignei.
3. Când un cursant termină un curs, serverul tău apelează POST /awards cu numele, emailul și data finalizării.
4. Salvezi awardId-ul returnat în înregistrarea finalizării.
5. Afișezi linkul de verificare în propriul produs, ca cursantul să-l vadă fără să plece de acolo.

Dacă preferi să nu scrii cod, același apel funcționează din orice instrument de automatizare care poate trimite o cerere HTTP cu corp JSON și un antet personalizat. Îndreaptă-l spre https://api.badges.ninja/awards și mapează câmpurile din formular sau foaia de calcul pe badgeId, recipient.name, recipient.email și issuedOn.

Planuri și limite bune de știut

API-ul este disponibil pe fiecare plan; nu plătești extra ca să-l deblochezi. Planul Free ($0) acoperă 2 emitenți, 5 insigne, 2 locuri, 1 cheie API și 1,200 de acreditări pe an. Starter costă $9 pe lună, iar Pro $29 pe lună, cu limite mai mari. Consultă pagina de prețuri pentru cifrele actuale înainte de a dimensiona o implementare. Dacă compari ce taxează alte platforme pentru accesul la API, Credly alternative pune costurile cap la cap.

Unde să mergi mai departe

• Referința completă a endpoint-urilor se află în documentația API, disponibilă în 40 de limbi.
• Pentru detalii despre autentificare și gestionarea cheilor, vezi ghidul de autentificare.
• Pentru codurile de eroare în detaliu, vezi referința de erori.
• Când ai depășit apelurile unul câte unul, folosește acordările în masă din panoul de control: încarci un CSV și poți pune execuția pe pauză sau o poți relua dacă e nevoie.

Prima acordare reușită e partea grea. După aceea, restul înseamnă să conectezi același apel în locurile unde realizările sunt deja înregistrate.

Ești gata să emiți prima ta acreditare verificabilă? Începe gratuit pe badges.ninja — designer vizual, pagină publică de verificare, certificat PDF, ieșire Open Badge v2.0. Fără card de credit.