Издавање Open Badges преко Badges Ninja REST API-ја: брзи почетак

Већини програма дигиталних потврда API никада не треба. Ако водите курс са неколико стотина полазника годишње, контролна табла ради све: дизајнирате дигиталну значку у визуелном дизајнеру, отпремите CSV и сваки прималац добија страницу за верификацију и PDF сертификат. Ако је то ваш случај, почните са како издати Open Badges из CSV-а и вратите се касније.

API се исплати када потврде треба да издаје неки други систем: ваша платформа за учење означи курс као завршен, ваш алат за регистрацију затвори догађај, ваш HR систем евидентира завршен модул о усклађености. У тим случајевима нико не жели да на крају сваке недеље извози табелу. Један HTTP позив у тренутку завршетка је једноставнији, а прималац добија своју значку док је достигнуће још свеже.

Овај брзи почетак води кроз цео пут у четири позива: узмете кључ, направите издаваоца, направите значку и доделите је. Затим погледамо како да примаоцу проследите везу за верификацију и како да проверите резултат. Сваки облик захтева у наставку потиче из примењених обрађивача, па га можете копирати и покренути.

Шта вам треба пре почетка

• Бесплатан налог на badges.ninja. План Free је довољан за овај водич: укључује 2 издаваоца, 5 значки, 2 места и 1 API кључ.
• Један API кључ, направљен са контролне табле.
• PNG или JPG за слику значке или значка коју сте дизајнирали у визуелном дизајнеру.

Основни URL за све је https://api.badges.ninja.

Корак 1: Направите API кључ

Пријавите се, отворите API Keys у бочној траци и кликните на Create API Key. Дајте му име које говори где ће се користити, на пример „LMS integration“, да бисте могли да разликујете кључеве кад их касније будете ротирали.

Кључ се приказује тачно једном. Одмах га копирајте у менаџер тајни или променљиву окружења. Кључеви изгледају као bws_ након чега следи 32 хексадецимална знака, а шаљу се у заглављу X-Api-Key са сваким захтевом. Опозив кључа са истог екрана ступа на снагу одмах.

Неколико навика које касније штеде муку:

• Никада не стављајте кључ у front-end код или јавно спремиште. API позивајте са сервера, serverless функције или алата за аутоматизацију.
• Користите један кључ по интеграцији. Ако један процури, опозивате једну интеграцију, а не све.
• Контролна табла прихвата и вашу пријављену сесију (Cognito JWT послат као Authorization: Bearer), али за скрипте и интеграције прави алат је API кључ.

Сви примери у наставку читају кључ из променљиве окружења под именом BADGES_API_KEY.

Корак 2: Направите издаваоца

Издавалац је организација која стоји иза значке. Појављује се на свакој страници за верификацију и унутар података Open Badge v2.0, зато користите име које људи заиста знају.

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

Обавезна поља су name (најмање 3 знака), url (важећа http или https адреса) и email. Опциона поља су logo (слика кодирана у base64) и linkedinOrganizationId, што укључује дугме „Додај у LinkedIn профил“ на вашим јавним страницама потврда.

Одговор садржи идентификатор издаваоца:

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

Задржите ту вредност тачно онако како је враћена. Она је улаз за следећи корак.

Верификација издаваоца

Значке се могу направити само под верификованим издаваоцем. Верификација функционише овако:

• Ако се имејл издаваоца поклапа са имејлом на вашем налогу, издавалац се верификује аутоматски. То је најбржи пут за први тест.
• Ако је имејл другачији, на ту адресу стиже имејл за верификацију са кодом. Код потврђујете на контролној табли (или преко API-ја за издаваоце) пре прављења значки.

Зато за овај водич користите исти имејл са којим сте се регистровали.

Корак 3: Направите значку

Значка је шаблон за вишекратну употребу: назив, опис, критеријуми и слика. Свака додела коју касније издате упућује на њу.

Захтев је обичан JSON. Слика се шаље као base64 ниска, па нема multipart отпремања са којим бисте се мучили. Префикс као што је data:image/png;base64, се прихвата и уклања.

JavaScript (Node 18 или новији):

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)

Свих пет поља (name, description, criteria, image, issuerId) је обавезно. Вреди знати два опциона: shareText, подразумевани текст који примаоци виде кад деле на друштвеним мрежама (подржава чуваре места {{badge_name}}, {{issuer_name}} и {{award_url}}), и designJson, који чува документ визуелног дизајнера како би се значка касније могла уређивати слој по слој.

Успех враћа HTTP 200 са { "badgeId": "<id>" }. Слика се трајно чува, а значка је сада Open Badge v2.0 BadgeClass који свако може да преузме.

Да ли уопште треба правити значке кодом?

Обично не. Дизајн значки је креативни задатак, а визуелни дизајнер (80+ шаблона, облици, иконе, 11 фонтова и сопствена отпремања) је много боље место за то од скрипте. Уобичајен образац је да се свака значка једном дизајнира на контролној табли, а да ваша интеграција само издаје доделе за њу. Своје значке можете излистати са GET /badges и копирати id оне која вам треба.

Значке правите преко API-ја када их генеришете програмски, на пример по једну за сваки курс у каталогу од стотина, или када припремате тестно окружење.

Корак 4: Доделите значку

Ово је позив који ће ваша интеграција упутити хиљадама пута. Пошаљите значку, примаоца и датум.

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"]

Правила на којима људи греше:

• recipient је угнежђени објекат са name и email. Равна поља као што је recipientEmail се одбацују.
• recipient.name мора имати најмање 5 знакова.
• issuedOn је обавезно. Пошаљите милисекунде од епохе или ISO датум као 2026-09-28.
• expires је опционо и прихвата исте формате.

Успех је HTTP 200 са телом које садржи awardId. Имејл примаоца се у подацима Open Badge чува као SHA-256 хеш, па га јавни JSON никада не открива.

Корак 5: Пронађите страницу за верификацију и Open Badge JSON

Одговор на доделу вам даје идентификатор, а не готову везу. Идентификатор се завршава GUID-ом, а јавне странице се граде од тог GUID-а:

• Страница за верификацију читљива људима: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Ако вам awardId стигне као пун URL, последњи сегмент путање користите као GUID.

Обе су јавне. Свако ко има везу може да верификује потврду без прављења налога, и у томе је поента: послодавац или службеник за упис треба да може да провери значку за десет секунди.

Преузмите JSON да видите шта свет види:

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

Добијате Open Badge v2.0 Assertion: значку на коју упућује, хеширани идентитет примаоца, датум издавања и блок за верификацију који упућује назад на хостовану тврдњу. Пошто су то стандардни подаци Open Badges, сваки алат који разуме формат може да их чита. Та преносивост је разлог да изаберете Open Badges уместо власничког PDF-а; Open Badges насупрот PDF сертификатима детаљније разматра тај компромис.

Како примаоци добијају потврду

Прављење доделе је одвојено од обавештавања примаоца. Примаоци могу отворити своје потврде преко портала за примаоце на badges.ninja/me, који користи пријаву magic link-ом без лозинке, и могу објавити јавни профил на badges.ninja/u/<handle>. Са странице за верификацију могу додати значку на LinkedIn, преузети PDF сертификат или поделити везу.

За првих неколико тестова пошаљите доделу на своју имејл адресу и прођите кроз искуство примаоца. То је најбржи начин да приметите ствари попут описа значке који звучи неспретно.

Руковање грешкама без муке

API користи обичне HTTP статусне кодове. Они на које ћете наићи:

Два практична савета. Прво, 400 третирајте као проблем са подацима и бележите тело одговора, јер оно именује поље које је проблематично. Друго, учините своју интеграцију идемпотентном са своје стране: чувајте awardId уз запис о завршетку у сопственој бази и проверите га пре поновног позивања API-ја. Тако поновљени webhook или поново покренут посао никада неће издати исто лице две потврде.

Састављање у стварну интеграцију

Типично повезивање изгледа овако:

1. Дизајнирајте значке на контролној табли, по једну за курс или етапу, и забележите ID сваке значке.
2. Чувајте у свом систему мапирање од курса до ID-ја значке.
3. Када полазник заврши курс, ваш сервер позива POST /awards са његовим именом, имејлом и датумом завршетка.
4. Сачувајте враћени awardId уз запис о завршетку.
5. Прикажите везу за верификацију унутар свог производа, да је полазник види а да га не напусти.

Ако радије не пишете код, исти позив ради из било ког алата за аутоматизацију који може да пошаље HTTP захтев са JSON телом и прилагођеним заглављем. Усмерите га на https://api.badges.ninja/awards и мапирајте поља свог обрасца или табеле на badgeId, recipient.name, recipient.email и issuedOn.

Планови и ограничења које вреди знати

API је доступан у сваком плану; не плаћате додатно да бисте га откључали. План Free ($0) покрива 2 издаваоца, 5 значки, 2 места, 1 API кључ и 1,200 потврда годишње. Starter кошта $9 месечно, а Pro $29 месечно, са вишим ограничењима. Погледајте страницу са ценама за тренутне бројеве пре него што димензионишете увођење. Ако поредите шта друге платформе наплаћују за приступ API-ју, алтернатива за Credly излаже трошкове један поред другог.

Куда даље

• Комплетна референца крајњих тачака налази се у API документацији, која је доступна на 40 језика.
• За детаље о аутентификацији и руковању кључевима погледајте водич за аутентификацију.
• За кодове грешака у дубину погледајте референцу грешака.
• Када прерастете један по један позив, користите масовне доделе на контролној табли: отпремите CSV и паузирајте или наставите извршавање по потреби.

Прва успешна додела је најтежа. После тога остаје само да исти позив уградите тамо где се достигнућа већ бележе.

Спремни да издате своју прву проверљиву потврду? Почните бесплатно на badges.ninja — визуелни дизајнер, јавна страница за верификацију, PDF сертификат, излаз Open Badge v2.0. Без кредитне картице.