Справочник на 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). Това е крайната точка, която модалният прозорец за редактиране на значка използва, за да възстанови отделните слоеве; крайната точка за списъка пропуска 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 — значката не е намерена