API издателей

Управление издателями значков — организациями или частными лицами, которые выдают значки.

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

Создание издателя

Создайте нового издателя значков.

POST /issuers

Параметры

Параметр	Тип	Обязательный	Описание
name	string	Да	Название организации (минимум 3 символа)
url	string	Да	Сайт организации (должен быть корректным HTTP/HTTPS URL)
email	string	Да	Контактный адрес электронной почты издателя
logo	string	Нет	Изображение в кодировке Base64 (PNG или JPG)
linkedinOrganizationId	string	Нет	Числовой ID страницы компании в LinkedIn. Если он задан, на каждой публичной странице credential этого издателя отображается кнопка Add to LinkedIn Profile.

Пример

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Ответ

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Примечания

• Учитывается в лимите издателей вашего плана (Free: 2, Starter: 5, Pro: 10). Квота не списывается.
• Если адрес электронной почты издателя совпадает с адресом вашей учётной записи, издатель верифицируется автоматически.
• Если адрес отличается, письмо для верификации отправляется на адрес издателя.
• После настройки издателя используйте Credentials API, чтобы начать выдавать credentials от имени этого издателя.

---

Список издателей

Получите всех созданных вами издателей.

GET /issuers

Пример

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

Ответ

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp — это время Unix epoch в миллисекундах. Если издателей больше, чем помещается на одной странице, дополнительно возвращается lastEvaluatedKey для постраничной навигации.

---

Верификация издателя

Верифицируйте издателя с помощью кода верификации, отправленного на его адрес электронной почты.

POST /issuers/{issuerId}/verify

Параметры

Параметр	Тип	Обязательный	Описание
issuerId	string	Да	ID издателя (параметр пути)
code	string	Да	Код верификации из письма

Пример

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Ответ

Простая строка:

"issuer has been verified"

---

Удаление издателя

Удалите издателя. У издателя не должно быть связанных с ним значков.

DELETE /issuers/{issuerId}

Пример

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ

Простая строка:

"issuer has been deleted"

Ошибки

• 400 — у издателя всё ещё есть связанные значки: issuer has {n} badge(s) linked — delete the badges first. Удаление блокируется только связанными значками — credentials удалению не мешают.
• 404 — издатель не найден

---

Обновление издателя

Обновите поля издателя. Редактировать можно только неверифицированных издателей — после верификации издателя эта конечная точка возвращает 400 verified issuers cannot be edited, чтобы сохранить стабильность credentials. Редактирование издателя заново генерирует его код верификации: если email совпадает с адресом электронной почты вашей учётной записи, издатель верифицируется повторно автоматически, в противном случае на этот адрес отправляется новое письмо для верификации.

PUT /issuers/{issuerId}

Параметры

Параметр	Тип	Обязательный	Описание
issuerId	string	Да	ID издателя (параметр пути)
name	string	Нет	Новое название
url	string	Нет	Новый URL
email	string	Нет	Новый адрес электронной почты (отправляется новое письмо для верификации, если он не совпадает с адресом вашей учётной записи)
logo	string	Нет	Новый логотип в кодировке Base64
linkedinOrganizationId	string	Нет	Новый ID организации в LinkedIn (или пустая строка для сброса)

Ответ

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Ошибки

• 400 — verified issuers cannot be edited (издатель уже верифицирован)
• 400 — not authorized (издатель принадлежит другой учётной записи)
• 404 — издатель не найден