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: същият вид от същия 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
    }
  }
}