Референца 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 — значка није пронађена