API wydań

Twórz i zarządzaj wydaniami odznak (assertions) — odznakami wystawionymi konkretnym odbiorcom.

Wszystkie endpointy wymagają uwierzytelnienia przez nagłówek X-Api-Key. Zobacz Uwierzytelnianie.

Utwórz wydanie

Wydaj odznakę odbiorcy.

POST /awards

Parametry

Parametr	Typ	Wymagany	Opis
badgeId	string	Tak	Identyfikator odznaki do wydania
recipient	object	Tak	Dane odbiorcy (patrz niżej)
recipient.name	string	Tak	Pełne imię i nazwisko odbiorcy (minimum 5 znaków)
recipient.email	string	Tak	Adres e-mail odbiorcy
issuedOn	string	Tak	Data wydania w formacie ISO 8601 (np. 2025-01-15)
expires	string	Nie	Data wygaśnięcia w formacie ISO 8601
blockchain	string	Nie	Blockchain dla weryfikacji on-chain. Obsługiwany jest tylko matchain. Dostępne w planie Pro.

Przykład

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

Odpowiedź

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

Uwagi

• Liczy się jako jedno wydanie względem twojego miesięcznego limitu (Free: 100/mies, Starter: 1 000/mies, Pro: 10 000/mies). Limit odnawia się w każdym okresie rozliczeniowym.
• Parametr blockchain dostępny jest tylko w planie Pro.

---

Lista wydań

Pobierz wydania z opcjonalnym filtrowaniem i paginacją.

GET /awards

Parametry query

Parametr	Typ	Wymagany	Opis
filter	JSON string	Nie	Obiekt filtra (patrz niżej)
lastEvaluatedKey	string	Nie	Token paginacji z poprzedniej odpowiedzi

Obiekt filtra

Parametr filter akceptuje JSON string z tymi polami:

Pole	Typ	Opis
badgeId	string	Filtruj po identyfikatorze odznaki.
search	string	Fragment do wyszukania w imionach lub e-mailach odbiorców (patrz searchField).
searchField	string	Albo name (domyślnie), albo email — która kolumna ma być przeszukiwana.

Paginacja przez lastEvaluatedKey działa z filtrami lub bez. Rozmiar strony to 50.

Przykład — lista wszystkich wydań

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

Przykład — filtrowanie po odznace

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"

Odpowiedź

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

Jeśli lastEvaluatedKey jest obecne w odpowiedzi, są dostępne kolejne wyniki. Przekaż je jako parametr query w następnym żądaniu, aby pobrać kolejną stronę.

---

Wyślij e-mail z wydaniem

Wyślij powiadomienie e-mail do odbiorcy o jego wydaniu.

POST /awards/{awardId}/send

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator wydania (parametr ścieżki i treści)
email	string	Tak	Adres e-mail odbiorcy

Przykład

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

Odpowiedź

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

---

Udostępnij wydanie

Udostępnij wydanie wielu odbiorcom e-mailem.

POST /awards/{awardId}/share

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator wydania (parametr ścieżki i treści)
recipients	string	Tak	Lista adresów e-mail rozdzielonych przecinkami
subject	string	Tak	Temat wiadomości e-mail
message	string	Tak	Treść wiadomości e-mail

Przykład

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

Odpowiedź

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

---

Pobierz certyfikat PDF

Generuj gotowy do druku certyfikat PDF A4 dla wydania.

GET /awards/{awardGuid}/pdf

Brak wymaganej autoryzacji — ten endpoint jest publiczny, aby odbiorcy mogli pobierać swoje certyfikaty.

Przykład

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

Odpowiedź to binarny PDF z nagłówkiem Content-Type: application/pdf.

---

Śledź zdarzenie wydania

Rejestruj zdarzenie zaangażowania (wyświetlenie, udostępnienie, pobranie, dodanie do LinkedIn). Używane przez publiczną stronę wydania do zbierania statystyk zaangażowania. Brak wymaganej autoryzacji.

POST /awards/{awardGuid}/event

Parametry

Parametr	Typ	Wymagany	Opis
kind	string	Tak	Jedno z view, share, download, linkedin_add.
network	string	Nie	Przy kind=share — sieć społecznościowa: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Tłumienie duplikatów per-IP: ten sam kind z tego samego IP liczony jest raz na 24 godziny.

Przykład

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

---

Pobierz statystyki wydania

Pobierz zbiorcze liczniki zaangażowania dla wydania.

GET /awards/{awardGuid}/stats

Brak wymaganej autoryzacji.

Odpowiedź

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