API посвідчень

Створюйте та керуйте посвідченнями (assertion) — значками, виданими конкретним одержувачам.

Усі кінцеві точки потребують автентифікації через заголовок X-Api-Key. Див. Автентифікація.

Створення посвідчення

Видайте значок одержувачу.

Потрібно видати значки сотням чи тисячам одержувачів одразу, а не робити окремий виклик API для кожної людини? Скористайтеся функцією інтерфейсу Масові посвідчення, яка приймає завантаження CSV-файлу.

POST /awards

Параметри

Параметр	Тип	Обов'язковий	Опис
badgeId	string	Так	Ідентифікатор значка, який потрібно видати
recipient	object	Так	Дані одержувача (див. нижче)
recipient.name	string	Так	Повне ім'я одержувача (щонайменше 5 символів)
recipient.email	string	Так	Адреса електронної пошти одержувача
issuedOn	string	Так	Дата видачі у форматі ISO 8601 (напр. 2025-01-15)
expires	string	Ні	Дата завершення дії у форматі ISO 8601

Приклад

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Відповідь

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Примітки

• Зараховується як одне посвідчення з вашого річного пулу посвідчень (Free: 1 200/рік, Starter: 12 000/рік, Pro: 120 000/рік). Пул — це гнучкий річний ліміт: витрачайте його, коли вам зручно протягом року, зокрема й великими партіями, — і він оновлюється в річницю реєстрації вашого облікового запису. Оплата залишається щомісячною; лише квота посвідчень є річною. Докладніше див. Плани та оплата.

---

Перелік посвідчень

Отримайте посвідчення з необов'язковою фільтрацією та пагінацією.

GET /awards

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
filter	JSON string	Ні	Об'єкт фільтра (див. нижче)
lastEvaluatedKey	string	Ні	Токен пагінації з попередньої відповіді

Об'єкт фільтра

Параметр filter приймає JSON-рядок з такими полями:

Поле	Тип	Опис
badgeId	string	Фільтр за ідентифікатором значка.
search	string	Підрядок для пошуку в іменах або адресах електронної пошти одержувачів (див. searchField).
searchField	string	name (за замовчуванням) або email — у якому стовпці шукати.

Пагінація через lastEvaluatedKey працює як із фільтрами, так і без них. Розмір сторінки — 50.

Приклад — перелік усіх посвідчень

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

Приклад — фільтр за значком

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Якщо у відповіді є lastEvaluatedKey, є й інші результати. Передайте його як параметр запиту в наступному запиті, щоб отримати наступну сторінку.

---

Надсилання листа про посвідчення

Надішліть одержувачу електронне сповіщення про його посвідчення.

POST /awards/{awardId}/send

Параметри

Параметр	Тип	Обов'язковий	Опис
awardId	string	Так	Ідентифікатор нагороди (параметр шляху й тіла)
email	string	Так	Адреса електронної пошти одержувача

Приклад

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Відповідь

Повертає простий рядок підтвердження:

"email sent"

---

Поширення посвідчення

Поділіться посвідченням із кількома одержувачами електронною поштою.

POST /awards/{awardId}/share

Параметри

Параметр	Тип	Обов'язковий	Опис
awardId	string	Так	Ідентифікатор нагороди (параметр шляху й тіла)
recipients	string	Так	Список адрес електронної пошти через кому
subject	string	Так	Тема листа
message	string	Так	Текст листа

Приклад

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Відповідь

Повертає простий рядок підтвердження:

"email sent"

---

Відкликання посвідчення

Відкличте посвідчення, яке ви видали. Розміщену assertion Open Badges v2.0 позначено revoked: true (з необов'язковою причиною), щоб будь-який верифікатор бачив, що значок більше недійсний. Запис посвідчення зберігається для аудиту, а кредит не повертається.

Відкликання також поширюється на Verifiable Credential Open Badges 3.0 цього посвідчення: біт нагороди перемикається в W3C Bitstring Status List, на який посилається credentialStatus у VC, тож гаманці VC також виявляють відкликання. Див. Відкликання (Bitstring Status List).

POST /awards/{awardId}/revoke

Параметри

Параметр	Тип	Обов'язковий	Опис
awardId	string	Так	Ідентифікатор нагороди (параметр шляху)
reason	string	Ні	Причина відкликання. Обрізається до 500 символів.
notify	boolean	Ні	Якщо true, надсилає одержувачу лист про відкликання його посвідчення. За замовчуванням false.

Приклад

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Відповідь

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Повторне відкликання вже відкликаного посвідчення ідемпотентне — повертається та сама відповідь без повторного надсилання сповіщення.

Масове відкликання

Щоб відкликати багато посвідчень одразу, скористайтеся надійною масовою кінцевою точкою з action: "revoke" замість виклику цієї кінцевої точки для кожної нагороди:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Вона повертає { "jobId", "total" }; завдання відкликає кожен ідентифікатор на стороні сервера (пропускаючи вже відкликані) і може бути відновлене. Уже відкликані та неіснуючі ідентифікатори позначаються як пропущені.

---

Видалення посвідчення

Остаточно видаліть посвідчення, яке ви видали. На відміну від відкликання, це повністю видаляє запис, а публічна сторінка посвідчення повертатиме 404. Використовуйте це для справжніх помилок (напр. видано не тій людині); для реальних посвідчень надавайте перевагу відкликанню, щоб assertion залишалася верифікованою як відкликана. Кредит не повертається.

DELETE /awards/{awardId}

Параметри

Параметр	Тип	Обов'язковий	Опис
awardId	string	Так	Ідентифікатор нагороди (параметр шляху)

Приклад

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Завантаження PDF-сертифіката

Створіть PDF-сертифікат формату A4, готовий до друку, для посвідчення.

GET /certify-badge/award/{awardGuid}/pdf

Автентифікація не потрібна — ця кінцева точка публічна, щоб одержувачі могли завантажити власний сертифікат.

Приклад

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

Відповідь — двійковий PDF із заголовком Content-Type: application/pdf.

---

Відстеження події посвідчення

Зафіксуйте подію взаємодії. Використовується публічною сторінкою посвідчення для наповнення статистики взаємодій. Автентифікація не потрібна.

POST /certify-badge/award/{awardGuid}/event

Параметри

Ця кінцева точка читає тіло безпосередньо (без обгортки parameters).

Параметр	Тип	Обов'язковий	Опис
event	string	Так	Одне з view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ні	Якщо event=share, соціальна мережа: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Придушення дублікатів за IP: та сама подія з тієї самої IP-адреси враховується один раз за 24 години.

Приклад

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Відповідь

{
  "ok": true
}

---

Отримання статистики посвідчення

Отримайте накопичувальні лічильники взаємодій для посвідчення.

GET /certify-badge/award/{awardGuid}/stats

Автентифікація не потрібна.

Відповідь

Лічильники повертаються за необробленим типом події. totals містить загальну кількість для кожної події; networks деталізує розподіл за мережами для подій, що мають network (наразі share). Події без зафіксованої активності просто відсутні.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}