Довідник API значків: створення, верифікація та отримання значків

Керуйте шаблонами значків — цифровими значками, які ви видаєте отримувачам.

Щоб видати цей значок одразу багатьом отримувачам через завантаження CSV замість API, див. Масові сертифікати.

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

Створити значок

Створіть новий значок для верифікованого емітента.

POST /badges

Параметри

Параметр	Тип	Обов’язковий	Опис
name	string	Так	Назва значка
description	string	Так	Що означає значок
criteria	string	Так	Що зробив отримувач, щоб отримати цей значок
image	string	Так	Зображення в кодуванні Base64 (PNG або JPG)
issuerId	string	Так	ID верифікованого емітента
shareText	string	Ні	Текст для поширення в соцмережах за замовчуванням для цього значка. Підтримує заповнювачі , та . Якщо не вказано, використовується вбудований текст за замовчуванням.
designJson	string	Ні	Серіалізований документ конструктора значків, який зберігається, щоб значок можна було пізніше редагувати по шарах.

Приклад

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Відповідь

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Примітки

• Перед створенням значків емітент має бути верифікований.
• Зображення зберігається в Amazon S3 і віддається через нашу глобальну CDN за незмінною URL-адресою, що залежить від вмісту.
• Коли клас значка створено, видавайте його отримувачам за допомогою API сертифікатів.

---

Список значків

Отримайте всі значки, які ви створили.

GET /badges

Приклад

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

Відповідь

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Отримати значок

Отримайте один значок разом із його текстом для поширення та серіалізованим документом конструктора значків (designJson). Саме цю кінцеву точку використовує модальне вікно редагування значка, щоб відновити окремі шари; кінцева точка списку пропускає designJson, щоб відповіді були компактними.

GET /badges/{badgeId}

Параметри

Параметр	Тип	Обов’язковий	Опис
badgeId	string	Так	ID значка (параметр шляху)

Приклад

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Текст для поширення завжди включено. Легший варіант списку GET /badges?badgeId={id} повертає той самий документ без designJson і включає текст для поширення лише за виклику з includeShareText=true.

---

Оновити значок

Оновіть наявний значок. Змінюються лише ті поля, які ви вкажете.

PUT /badges/{badgeId}

Параметри

Параметр	Тип	Обов’язковий	Опис
badgeId	string	Так	ID значка (параметр шляху)
name	string	Ні	Нова назва значка
description	string	Ні	Новий опис
criteria	string	Ні	Нові критерії
image	string	Ні	Нове зображення в кодуванні Base64
designJson	string	Ні	Новий серіалізований документ конструктора значків.

Приклад

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Відповідь

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Оновити текст для поширення

Задайте користувацький текст, який відображається, коли отримувачі діляться цим значком у соціальних мережах.

PUT /badges/{badgeId}/share-text

Параметри

Параметр	Тип	Обов’язковий	Опис
badgeId	string	Так	ID значка (параметр шляху)
text	string	Так	Текст для поширення (HTML заборонено)

Приклад

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Відповідь

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Видалити значок

Видаліть значок. У значка не повинно бути сертифікатів.

DELETE /badges/{badgeId}

Приклад

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь

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

"badge has been deleted"

Помилки

• 400 — за значком досі є видані сертифікати: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — значок не знайдено