API емітентів

Керуйте емітентами значків — організаціями чи особами, що видають значки.

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

Створити емітента

Створити нового емітента значків.

POST /issuers

Параметри

Параметр	Тип	Обов’язковий	Опис
name	string	Так	Назва організації (мінімум 3 символи)
url	string	Так	Вебсайт організації (має бути дійсним HTTP/HTTPS URL)
email	string	Так	Контактна електронна адреса емітента
logo	string	Ні	Зображення в кодуванні Base64 (PNG або JPG)
linkedinOrganizationId	string	Ні	Числовий ID сторінки компанії в LinkedIn. Якщо вказано, кожна публічна сторінка облікових даних цього емітента показує кнопку 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). Квота не списується.
• Якщо адреса електронної пошти емітента збігається з адресою вашого облікового запису, емітент верифікується автоматично.
• Якщо адреса інша, на пошту емітента надсилається лист для верифікації.
• Після налаштування емітента використовуйте API облікових даних, щоб почати видавати облікові дані від імені цього емітента.

---

Список емітентів

Отримати всіх створених вами емітентів.

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-час у мілісекундах. Якщо емітентів більше, ніж вміщується на одній сторінці, для пагінації додатково повертається 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. Видалення блокується лише прив’язаними значками — облікові дані його не блокують.
• 404 — емітента не знайдено

---

Оновити емітента

Оновіть поля емітента. Редагувати можна лише неверифікованих емітентів — щойно емітента верифіковано, цей ендпоінт повертає 400 verified issuers cannot be edited, щоб зберегти стабільність облікових даних. Редагування емітента повторно генерує його код верифікації: якщо 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 — емітента не знайдено