API credential

Создание и управление credential (assertion) — цифровыми значками, выданными конкретным получателям.

Все конечные точки требуют аутентификации через заголовок X-Api-Key. См. Аутентификация.

Создание credential

Выдача значка получателю.

Нужно выдать значки сотням или тысячам получателей сразу, а не делать отдельный вызов API для каждого? Воспользуйтесь функцией интерфейса Массовая выдача credential, которая принимает CSV-файл.

POST /awards

Параметры

Параметр	Тип	Обязательный	Описание
badgeId	string	Да	ID выдаваемого значка
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"
}

Примечания

• Расходует один credential из вашего годового пула credential (Free: 1 200/год, Starter: 12 000/год, Pro: 120 000/год). Пул — это гибкий годовой лимит: тратьте его когда угодно в течение года, в том числе всплесками; он обновляется в годовщину регистрации вашего аккаунта. Оплата по-прежнему помесячная; годовой только лимит credential. Подробнее см. Тарифы и оплата.

---

Список credential

Получение credential с необязательной фильтрацией и постраничной выдачей.

GET /awards

Параметры запроса

Параметр	Тип	Обязательный	Описание
filter	строка JSON	Нет	Объект фильтра (см. ниже)
lastEvaluatedKey	string	Нет	Токен постраничной выдачи из предыдущего ответа

Объект фильтра

Параметр filter принимает строку JSON со следующими полями:

Поле	Тип	Описание
badgeId	string	Фильтр по ID значка.
search	string	Подстрока для поиска в именах или адресах электронной почты получателей (см. searchField).
searchField	string	Либо name (по умолчанию), либо email — в каком столбце искать.

Постраничная выдача через lastEvaluatedKey работает как с фильтрами, так и без них. Размер страницы — 50.

Пример — список всех credential

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, значит, есть и другие результаты. Передайте его как параметр запроса в следующем запросе, чтобы получить следующую страницу.

---

Отправка письма о credential

Отправка получателю уведомления по электронной почте о его credential.

POST /awards/{awardId}/send

Параметры

Параметр	Тип	Обязательный	Описание
awardId	string	Да	ID credential (параметр пути и тела запроса)
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"

---

Публикация credential

Отправка credential по электронной почте нескольким получателям.

POST /awards/{awardId}/share

Параметры

Параметр	Тип	Обязательный	Описание
awardId	string	Да	ID credential (параметр пути и тела запроса)
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"

---

Отзыв credential

Отзыв выданного вами credential. Размещённый assertion Open Badges v2.0 помечается как revoked: true (с необязательной причиной), так что любое средство верификации видит, что значок больше недействителен. Запись о credential сохраняется для аудита, кредиты не возвращаются.

Отзыв распространяется и на Verifiable Credential Open Badges 3.0 этого credential: бит награды переключается в Bitstring Status List W3C, на который ссылается credentialStatus в VC, поэтому его обнаруживают и VC-кошельки. См. Отзыв (Bitstring Status List).

POST /awards/{awardId}/revoke

Параметры

Параметр	Тип	Обязательный	Описание
awardId	string	Да	ID credential (параметр пути)
reason	string	Нет	Причина отзыва. Обрезается до 500 символов.
notify	boolean	Нет	Если true, получателю отправляется письмо о том, что его credential отозван. По умолчанию 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"
}

Повторный отзыв уже отозванного credential идемпотентен — возвращается тот же ответ, а уведомление повторно не отправляется.

Массовый отзыв

Чтобы отозвать много credential сразу, используйте надёжную конечную точку массовых операций с 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" }; задание отзывает каждый ID на стороне сервера (пропуская уже отозванные) и может быть возобновлено. Уже отозванные и несуществующие ID сообщаются как пропущенные.

---

Удаление credential

Безвозвратное удаление выданного вами credential. В отличие от отзыва, запись удаляется полностью, а публичная страница credential будет возвращать 404. Используйте это для настоящих ошибок (например, выдано не тому человеку); для реальных credential предпочитайте отзыв, чтобы assertion оставался проверяемым как отозванный. Кредиты не возвращаются.

DELETE /awards/{awardId}

Параметры

Параметр	Тип	Обязательный	Описание
awardId	string	Да	ID credential (параметр пути)

Пример

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 для credential.

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.

---

Отслеживание события credential

Запись события вовлечённости. Используется публичной страницей credential для наполнения статистики вовлечённости. Аутентификация не требуется.

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
}

---

Получение статистики credential

Получение накопленных счётчиков вовлечённости для credential.

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