Издаване на Open Badges чрез REST API на Badges Ninja: бърз старт

Повечето програми за дигитални удостоверения никога не се нуждаят от 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. Имейлът на получателя се съхранява като SHA-256 хеш в данните на Open Badge, така че публичният 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. Без кредитна карта.