Справочник 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). Этот эндпоинт использует окно Edit Badge, чтобы восстановить отдельные слои; эндпоинт списка не возвращает 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 — значок не найден