API за акредитиве

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

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

Креирање акредитива

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

Треба да издате стотинама или хиљадама прималаца одједном уместо једног API позива по особи? Користите функцију корисничког интерфејса Масовни акредитиви, која прихвата CSV отпремање.

POST /awards

Параметри

Параметар	Тип	Обавезан	Опис
badgeId	string	Да	ИД значке коју издајете
recipient	object	Да	Подаци о примаоцу (погледајте испод)
recipient.name	string	Да	Пуно име примаоца (најмање 5 карактера)
recipient.email	string	Да	Адреса е-поште примаоца
issuedOn	string	Да	Датум издавања у ISO 8601 формату (нпр. 2025-01-15)
expires	string	Не	Датум истека у ISO 8601 формату

Пример

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

Одговор

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

Напомене

• Рачуна се као један акредитив из вашег годишњег фонда акредитива (Free: 1.200/годишње, Starter: 12.000/годишње, Pro: 120.000/годишње). Фонд је флексибилна годишња квота — потрошите је кад год желите током године, укључујући и у налетима — и ресетује се на годишњицу регистрације вашег налога. Наплата остаје месечна; само је квота акредитива годишња. Детаље погледајте у Планови и наплата.

---

Листа акредитива

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

GET /awards

Параметри упита

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

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

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

Поље	Тип	Опис
badgeId	string	Филтрирање по ИД-у значке.
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"

Одговор

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "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 присутан у одговору, постоји још резултата. Проследите га као параметар упита у следећем захтеву да добијете следећу страницу.

---

Слање е-поште о акредитиву

Пошаљите примаоцу обавештење е-поштом о његовом акредитиву.

POST /awards/{awardId}/send

Параметри

Параметар	Тип	Обавезан	Опис
awardId	string	Да	ИД доделе (параметар путање и тело)
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"
    }
  }'

Одговор

Враћа једноставан потврдни стринг:

"email sent"

---

Дељење акредитива

Поделите акредитив са више прималаца путем е-поште.

POST /awards/{awardId}/share

Параметри

Параметар	Тип	Обавезан	Опис
awardId	string	Да	ИД доделе (параметар путање и тело)
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."
    }
  }'

Одговор

Враћа једноставан потврдни стринг:

"email sent"

---

Опозив акредитива

Опозовите акредитив који сте издали. Хостована тврдња Open Badges v2.0 означава се са revoked: true (са необавезним разлогом) тако да сваки верификатор види да значка више није важећа. Запис акредитива се чува ради ревизије, а кредит се не враћа.

Опозив се шири и на Open Badges 3.0 Verifiable Credential акредитива: бит доделе се преклопи у W3C Bitstring Status List на коју упућује credentialStatus VC-а, па опозив региструју и VC новчаници. Погледајте Опозив (Bitstring Status List).

POST /awards/{awardId}/revoke

Параметри

Параметар	Тип	Обавезан	Опис
awardId	string	Да	ИД доделе (параметар путање)
reason	string	Не	Разлог опозива. Скраћује се на 500 карактера.
notify	boolean	Не	Када је true, е-поштом обавештава примаоца да је његов акредитив опозван. Подразумевано false.

Пример

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Одговор

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Опозив већ опозваног акредитива је идемпотентан — враћа исти одговор без поновног слања обавештења.

Масовни опозив

Да бисте опозвали више акредитива одједном, користите трајну масовну крајњу тачку са action: "revoke" уместо позивања ове крајње тачке за сваку доделу:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Враћа { "jobId", "total" }; посао на серверу опозива сваки ИД (већ опозване прескаче) и може се наставити. Већ опозвани и непостојећи ИД-ови пријављују се као прескочени.

---

Брисање акредитива

Трајно обришите акредитив који сте издали. За разлику од опозива, ово у потпуности уклања запис, а јавна страница акредитива враћа 404. Користите за праве грешке (нпр. издато погрешној особи); за праве акредитиве радије користите опозив да тврдња остане проверљива као опозвана. Кредит се не враћа.

DELETE /awards/{awardId}

Параметри

Параметар	Тип	Обавезан	Опис
awardId	string	Да	ИД доделе (параметар путање)

Пример

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Одговор

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

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

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

GET /certify-badge/award/{awardGuid}/pdf

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

Пример

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

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

---

Бележење догађаја акредитива

Забележите догађај ангажовања. Користи га јавна страница акредитива за попуњавање статистике ангажовања. Аутентификација није потребна.

POST /certify-badge/award/{awardGuid}/event

Параметри

Ова крајња тачка чита тело директно (без омотача parameters).

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

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

Пример

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

Одговор

{
  "ok": true
}

---

Преузимање статистике акредитива

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

GET /certify-badge/award/{awardGuid}/stats

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

Одговор

Бројачи се враћају по сировом типу догађаја. totals садржи укупан број за сваки догађај; networks разлаже поделу по мрежама за догађаје који носе network (тренутно share). Догађаји без забележене активности једноставно изостају.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}