API за награде

Креирајте и управљајте наградама значки (assertion-има) — значкама додељеним одређеним примаоцима.

Све крајње тачке захтевају аутентификацију преко заглавља X-Api-Key. Видите Аутентификација.

Креирање награде

Доделите значку примаоцу.

POST /awards

Параметри

Параметар	Тип	Обавезно	Опис
badgeId	string	Да	ID значке за доделу
recipient	object	Да	Детаљи примаоца (видети испод)
recipient.name	string	Да	Пуно име примаоца (минимум 5 карактера)
recipient.email	string	Да	Имејл адреса примаоца
issuedOn	string	Да	Датум издавања у ISO 8601 формату (нпр. 2025-01-15)
expires	string	Не	Датум истека у ISO 8601 формату
blockchain	string	Не	Блокчејн за on-chain верификацију. Подржан је само matchain. Доступно на плану Pro.

Пример

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Одговор

{
  "statusCode": 200,
  "info": {
    "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
  }
}

Напомене

• Рачуна се као једна награда у месечном лимиту (Free: 100/мес, Starter: 1 000/мес, Pro: 10 000/мес). Лимит се ресетује сваког обрачунског периода.
• Параметар blockchain доступан је само на плану Pro.

---

Листа награда

Преузми награде са опционим филтрирањем и пагинацијом.

GET /awards

Query параметри

Параметар	Тип	Обавезно	Опис
filter	JSON string	Не	Објекат филтера (видети испод)
lastEvaluatedKey	string	Не	Токен пагинације из претходног одговора

Објекат филтера

Параметар filter прихвата JSON низ са овим пољима:

Поље	Тип	Опис
badgeId	string	Филтер по ID-ју значке.
search	string	Подниз за тражење у именима или имејловима прималаца (видети searchField).
searchField	string	name (подразумевано) или email — у којој колони тражити.

Пагинација преко lastEvaluatedKey ради са и без филтера. Величина странице је 50.

Пример — све награде

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

Пример — филтер по значки

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Одговор

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "recipient": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        },
        "issuedOn": "2025-01-15T00:00:00.000Z",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ],
    "lastEvaluatedKey": "eyJ..."
  }
}

Ако је lastEvaluatedKey присутан у одговору, постоји још резултата. Проследите га као query параметар у следећем захтеву да добијете следећу страницу.

---

Слање имејла о награди

Пошаљите имејл обавештење примаоцу о његовој награди.

POST /awards/{awardId}/send

Параметри

Параметар	Тип	Обавезно	Опис
awardId	string	Да	ID награде (path параметар и body)
email	string	Да	Имејл адреса примаоца

Пример

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Одговор

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

---

Дељење награде

Поделите награду са више прималаца путем имејла.

POST /awards/{awardId}/share

Параметри

Параметар	Тип	Обавезно	Опис
awardId	string	Да	ID награде (path параметар и body)
recipients	string	Да	Листа имејл адреса одвојена зарезима
subject	string	Да	Наслов имејла
message	string	Да	Тело поруке

Пример

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Одговор

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

---

Преузимање PDF сертификата

Генеришите A4 PDF сертификат спреман за штампу за награду.

GET /awards/{awardGuid}/pdf

Аутентификација није потребна — ова крајња тачка је јавна како би примаоци могли да преузму свој сертификат.

Пример

curl -OJ https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

Одговор је бинарни PDF са заглављем Content-Type: application/pdf.

---

Праћење догађаја награде

Забележите догађај ангажовања (view, share, download, LinkedIn add). Користи јавна страница награде за попуњавање статистике. Аутентификација није потребна.

POST /awards/{awardGuid}/event

Параметри

Параметар	Тип	Обавезно	Опис
kind	string	Да	Једно од view, share, download, linkedin_add.
network	string	Не	Када је kind=share, друштвена мрежа: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Потискивање дупликата по IP: исти kind са истог IP-а се рачуна једном у 24 часа.

Пример

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"kind": "share", "network": "linkedin"}}'

---

Добијање статистике награде

Преузми кумулативне бројаче ангажовања за награду.

GET /awards/{awardGuid}/stats

Аутентификација није потребна.

Одговор

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}