API нагород

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

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

Створити нагороду

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

POST /awards

Параметри

Параметр	Тип	Обовʼязково	Опис
badgeId	string	Так	ID значка для видачі
recipient	object	Так	Дані одержувача (див. нижче)
recipient.name	string	Так	Повне імʼя одержувача (мінімум 5 символів)
recipient.email	string	Так	E-mail одержувача
issuedOn	string	Так	Дата видачі у форматі ISO 8601 (наприклад, 2025-01-15)
expires	string	Ні	Дата закінчення у форматі ISO 8601
blockchain	string	Ні	Блокчейн для on-chain-верифікації. Підтримується лише matchain. Доступний на тарифі Pro.

Приклад

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

Відповідь

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

Примітки

• Зараховується як одна нагорода в місячну квоту (Free: 100/міс, Starter: 1 000/міс, Pro: 10 000/міс). Квота обнулюється кожен білінговий період.
• Параметр blockchain доступний лише на тарифі Pro.

---

Список нагород

Отримати нагороди з опційною фільтрацією та пагінацією.

GET /awards

Query-параметри

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

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

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

Поле	Тип	Опис
badgeId	string	Фільтр за ID значка.
search	string	Підрядок для пошуку в іменах чи e-mail одержувачів (див. 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"

Відповідь

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "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, є ще результати. Передайте його як query-параметр у наступному запиті, щоб отримати наступну сторінку.

---

Надіслати лист про нагороду

Надіслати одержувачу повідомлення про нагороду по e-mail.

POST /awards/{awardId}/send

Параметри

Параметр	Тип	Обовʼязково	Опис
awardId	string	Так	ID нагороди (path-параметр і body)
email	string	Так	E-mail одержувача

Приклад

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

Відповідь

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

Поділитися нагородою

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

POST /awards/{awardId}/share

Параметри

Параметр	Тип	Обовʼязково	Опис
awardId	string	Так	ID нагороди (path-параметр і body)
recipients	string	Так	Список e-mail через кому
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."
    }
  }'

Відповідь

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

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

Згенерувати готовий до друку PDF-сертифікат A4 для нагороди.

GET /awards/{awardGuid}/pdf

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

Приклад

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

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

---

Відстежити подію нагороди

Записати подію залучення (view, share, download, LinkedIn add). Використовується публічною сторінкою нагороди для наповнення статистики. Автентифікація не потрібна.

POST /awards/{awardGuid}/event

Параметри

Параметр	Тип	Обовʼязково	Опис
kind	string	Так	Одне з view, share, download, linkedin_add.
network	string	Ні	При kind=share, соцмережа: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

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

Приклад

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

---

Отримати статистику нагороди

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

GET /awards/{awardGuid}/stats

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

Відповідь

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}