API за значки

Управлявайте шаблони за значки — удостоверенията, които награждавате на получатели.

Всички крайни точки изискват удостоверяване през хедъра X-Api-Key. Вижте Удостоверяване.

Създаване на значка

Създайте нова значка под потвърден издател.

POST /badges

Параметри

Параметър	Тип	Задължителен	Описание
name	string	Да	Заглавие на значката
description	string	Да	Какво представлява значката
criteria	string	Да	Какво е направил получателят, за да заслужи значката
image	string	Да	Base64-кодирано изображение (PNG или JPG)
issuerId	string	Да	ID на потвърден издател

Пример

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

Отговор

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

Бележки

• Издателят трябва да е потвърден преди създаването на значки.
• Изображението се качва в IPFS за постоянно съхранение.

---

Списък със значки

Извлечете всички създадени от вас значки.

GET /badges

Пример

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

Отговор

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Обновяване на значка

Обновете съществуваща значка. Променят се само полетата, които подавате.

PUT /badges/{badgeId}

Параметри

Параметър	Тип	Задължителен	Описание
badgeId	string	Да	ID на значката (path параметър)
name	string	Не	Ново заглавие
description	string	Не	Ново описание
criteria	string	Не	Нови критерии
image	string	Не	Ново base64-кодирано изображение

Пример

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

Отговор

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

---

Обновяване на текст за споделяне

Задайте персонализиран текст, показван когато получателите споделят значката в социалните мрежи.

PUT /badges/{badgeId}/share-text

Параметри

Параметър	Тип	Задължителен	Описание
badgeId	string	Да	ID на значката (path параметър)
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:"
    }
  }'

Отговор

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

Изтриване на значка

Изтрийте значка. Значката не трябва да има награди.

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"

Отговор

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Грешки

• 400 — значката има награди и не може да бъде изтрита
• 404 — значката не е намерена