API за сертификати

Създавайте и управлявайте сертификати (assertions) — значки, издадени на конкретни получатели.

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

Създаване на сертификат

Издайте значка на получател.

Трябва да издадете на стотици или хиляди получатели наведнъж, вместо една API заявка на човек? Използвайте функцията Масови сертификати в интерфейса, която приема качване на CSV файл.

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

Пример

bash

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

Отговор

json

{
  "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	Филтриране по ID на значката.
`search`	string	Подниз, който се търси в имената или имейлите на получателите (вижте `searchField`).
`searchField`	string	`name` (по подразбиране) или `email` — в коя колона да се търси.

Страницирането чрез lastEvaluatedKey работи със и без филтри. Размерът на страницата е 50.

Пример — списък с всички сертификати

bash

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

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

bash

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"

Отговор

json

{
  "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	Да	ID на сертификата (параметър на пътя и на тялото)
`email`	string	Да	Имейл адрес на получателя

Пример

bash

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

Отговор

Връща обикновен низ за потвърждение:

json

"email sent"

Споделяне на сертификат

Споделете сертификат с няколко получатели по имейл.

POST /awards/{awardId}/share

Параметри

Параметър	Тип	Задължителен	Описание
`awardId`	string	Да	ID на сертификата (параметър на пътя и на тялото)
`recipients`	string	Да	Списък с имейл адреси, разделени със запетая
`subject`	string	Да	Тема на имейла
`message`	string	Да	Текст на имейла

Пример

bash

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

Отговор

Връща обикновен низ за потвърждение:

json

"email sent"

Отмяна на сертификат

Отменете сертификат, който сте издали. Хостваният assertion на Open Badges v2.0 се маркира с revoked: true (с по избор причина), така че всеки верификатор да вижда, че значката вече не е валидна. Записът на сертификата се запазва за целите на одита и не се възстановява кредит.

Отмяната се разпространява и към Verifiable Credential на Open Badges 3.0 на сертификата: битът на наградата се превключва в Bitstring Status List на W3C, посочен от credentialStatus на VC, така че и VC портфейлите я откриват. Вижте Отмяна (Bitstring Status List).

POST /awards/{awardId}/revoke

Параметри

Параметър	Тип	Задължителен	Описание
`awardId`	string	Да	ID на сертификата (параметър на пътя)
`reason`	string	Не	Причина за отмяната. Съкращава се до 500 символа.
`notify`	boolean	Не	Когато е `true`, уведомява получателя по имейл, че сертификатът му е отменен. По подразбиране `false`.

Пример

bash

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

Отговор

json

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

Отмяната на вече отменен сертификат е идемпотентна — връща същия отговор, без да изпраща повторно известие.

Масова отмяна

За да отмените много сертификати наведнъж, използвайте трайната масова крайна точка с action: "revoke" вместо да извиквате тази крайна точка за всеки сертификат:

bash

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. Използвайте го за истински грешки (напр. издаден на грешен човек); за реални сертификати предпочитайте отмяна, така че assertion да остане проверим като отменен. Не се възстановява кредит.

DELETE /awards/{awardId}

Параметри

Параметър	Тип	Задължителен	Описание
`awardId`	string	Да	ID на сертификата (параметър на пътя)

Пример

bash

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

Отговор

json

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

Изтегляне на PDF сертификат

Генерирайте A4 PDF сертификат, готов за печат, за даден сертификат.

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

Не се изисква удостоверяване — тази крайна точка е публична, за да могат получателите да изтеглят собствения си сертификат.

Пример

bash

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 часа.

Пример

bash

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

Отговор

json

{
  "ok": true
}

Получаване на статистика за сертификат

Извлечете натрупаните броячи на ангажираност за сертификат.

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

Не се изисква удостоверяване.

Отговор

Броячите се връщат с ключ суровия тип събитие. totals съдържа общия брой за всяко събитие; networks показва разбивката по мрежи за събития, които носят network (в момента share). Събития без записана активност просто липсват.

json

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

API за сертификати ​

Създаване на сертификат ​

Параметри ​

Пример ​

Отговор ​

Бележки ​

Списък със сертификати ​

Параметри на заявката ​

Обект на филтъра ​

Пример — списък с всички сертификати ​

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

Отговор ​

Изпращане на имейл за сертификата ​

Параметри ​

Пример ​

Отговор ​

Споделяне на сертификат ​

Параметри ​

Пример ​

Отговор ​

Отмяна на сертификат ​

Параметри ​

Пример ​

Отговор ​

Масова отмяна ​

Изтриване на сертификат ​

Параметри ​

Пример ​

Отговор ​

Изтегляне на PDF сертификат ​

Пример ​

Проследяване на събитие за сертификат ​

Параметри ​

Пример ​

Отговор ​

Получаване на статистика за сертификат ​

Отговор ​

API за сертификати

Създаване на сертификат

Параметри

Пример

Отговор

Бележки

Списък със сертификати

Параметри на заявката

Обект на филтъра

Пример — списък с всички сертификати

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

Отговор

Изпращане на имейл за сертификата

Параметри

Пример

Отговор

Споделяне на сертификат

Параметри

Пример

Отговор

Отмяна на сертификат

Параметри

Пример

Отговор

Масова отмяна

Изтриване на сертификат

Параметри

Пример

Отговор

Изтегляне на PDF сертификат

Пример

Проследяване на събитие за сертификат

Параметри

Пример

Отговор

Получаване на статистика за сертификат

Отговор