Видача Open Badges через REST API Badges Ninja: швидкий старт
Автентифікуйтеся, створіть емітента, розробіть або завантажте значок і видайте його отримувачу — усе через REST. Додано приклади на JavaScript і Python.
Автор Nacho Coll Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure.
Більшості програм сертифікації 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 з кожним запитом. Відкликання ключа на тому самому екрані діє негайно.
Кілька звичок, що заощадять клопоту:
- Ніколи не кладіть ключ у фронтенд-код чи публічний репозиторій. Викликайте 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, що вмикає кнопку Add to LinkedIn Profile на ваших публічних сторінках посвідчень.
Відповідь містить ідентифікатор емітента:
{
"issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Збережіть це значення точно таким, яким воно повернулося. Це вхідні дані наступного кроку.
Верифікація емітента
Значки можна створювати лише під верифікованим емітентом. Верифікація працює так:
- Якщо e-mail емітента збігається з e-mail вашого акаунта, емітент верифікується автоматично. Це найшвидший шлях для першого тесту.
- Якщо e-mail інший, на цю адресу надходить лист із кодом верифікації. Ви підтверджуєте код у панелі (або через API емітентів) перед створенням значків.
Тож для цього туторіалу використайте той самий e-mail, з яким реєструвалися.
Крок 3: Створіть значок
Значок — це багаторазовий шаблон: назва, опис, критерії та зображення. Кожна видача надалі посилається на нього.
Запит — звичайний JSON. Зображення передається як рядок base64, тож жодного multipart-завантаження, з яким довелося б боротися. Префікс data URL, як-от 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>" }. Зображення зберігається назавжди, а значок тепер — це BadgeClass Open Badge v2.0, який може отримати будь-хто.
Чи варто взагалі створювати значки кодом?
Зазвичай ні. Дизайн значка — творче завдання, і візуальний дизайнер (понад 80 шаблонів, форми, іконки, 11 шрифтів і власні завантаження) — набагато кращe місце для цього, ніж скрипт. Поширений підхід: розробити кожен значок один раз у панелі, а ваша інтеграція лише видає нагороди за ним. Список значків можна отримати через 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. E-mail отримувача зберігається в даних Open Badge як хеш SHA-256, тож публічний JSON його ніколи не розкриває.
Крок 5: Знайдіть сторінку верифікації та JSON Open Badge
Відповідь на видачу дає ідентифікатор, а не готове посилання. Ідентифікатор закінчується GUID, і з нього будуються публічні сторінки:
- Зрозуміла людині сторінка верифікації:
https://badges.ninja/awards/<awardId> - JSON-LD Open Badge v2.0:
https://api.badges.ninja/certify-badge/award/<awardId>
Якщо ваш awardId повертається як повна URL-адреса, візьміть останній сегмент шляху як GUID.
Обидві сторінки публічні. Будь-хто з посиланням може верифікувати посвідчення без створення акаунта — у цьому й сенс: роботодавець чи приймальна комісія має змогу перевірити значок за десять секунд.
Отримайте JSON, щоб побачити те, що бачить світ:
curl https://api.badges.ninja/certify-badge/award/<awardId>Ви отримуєте твердження (Assertion) Open Badge v2.0: значок, на який воно посилається, захешовану особу отримувача, дату видачі та блок верифікації, що вказує на розміщене твердження. Оскільки це стандартні дані Open Badges, їх прочитає будь-який інструмент, що розуміє формат. Ця переносимість — причина обрати Open Badges замість пропрієтарного PDF; Open Badges проти PDF-сертифікатів розглядає цей компроміс глибше.
Як отримувачі отримують посвідчення
Створення нагороди — окрема дія від повідомлення про неї отримувача. Отримувачі можуть відкрити свої посвідчення через портал отримувача на badges.ninja/me, що використовує вхід за magic-посиланням без пароля, і можуть опублікувати публічний профіль на badges.ninja/u/<handle>. Зі сторінки верифікації вони можуть додати значок до LinkedIn, завантажити сертифікат у PDF або поділитися посиланням.
Для перших тестів надішліть нагороду на власну адресу e-mail і пройдіть увесь шлях отримувача. Це найшвидший спосіб помітити, скажімо, незграбно сформульований опис значка.
Обробка помилок, що не болить
API використовує звичайні коди стану HTTP. Ось ті, з якими ви зустрінетеся:
| Статус | Значення | Що робити |
|---|---|---|
| 200 | Успіх | Прочитайте тіло JSON |
| 400 | Поле відсутнє або недійсне, зокрема ім’я отримувача коротше за 5 символів | Виправте дані; повторення того самого запиту знову завершиться помилкою |
| 401 | Відсутній або хибний API-ключ | Перевірте заголовок X-Api-Key і чи ключ не відкликано |
| 402 | Закінчилися кредити або квота плану | Перейдіть на вищий план або дочекайтеся наступного періоду квоти |
| 404 | Значок не знайдено | Перевірте badgeId, який ви передали |
Дві практичні поради. По-перше, сприймайте 400 як проблему з даними й логуйте тіло відповіді: воно називає поле з помилкою. По-друге, зробіть інтеграцію ідемпотентною на своєму боці: зберігайте awardId поруч із записом про завершення у власній базі даних і перевіряйте його перед повторним викликом API. Так повторений вебхук чи повторно запущене завдання ніколи не видасть одній людині два посвідчення.
Збираємо все разом у справжню інтеграцію
Типове підключення виглядає так:
- Розробіть значки в панелі, по одному на курс чи віху, і занотуйте ідентифікатор кожного.
- Збережіть у своїй системі відповідність курсу та ідентифікатора значка.
- Коли студент завершує курс, ваш сервер викликає
POST /awardsз його ім’ям, e-mail і датою завершення. - Збережіть повернений
awardIdу записі про завершення. - Покажіть посилання на верифікацію всередині власного продукту, щоб студент бачив його, не полишаючи його.
Якщо ви волієте не писати код, той самий виклик працює з будь-якого інструмента автоматизації, що вміє надсилати 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. Кредитна картка не потрібна.
Про автора
Nacho Coll
Founder & Engineer at Badges Ninja
Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.
