API poświadczeń

Twórz poświadczenia (assertions) i zarządzaj nimi — odznakami wystawionymi konkretnym odbiorcom.

Wszystkie endpointy wymagają uwierzytelnienia za pomocą nagłówka X-Api-Key. Zobacz Uwierzytelnianie.

Utwórz poświadczenie

Wystawia odznakę odbiorcy.

Musisz wystawić poświadczenia setkom lub tysiącom odbiorców naraz, zamiast wykonywać jedno wywołanie API na osobę? Skorzystaj z funkcji interfejsu Poświadczenia zbiorcze, która przyjmuje przesłany plik CSV.

POST /awards

Parametry

Parametr	Typ	Wymagany	Opis
badgeId	string	Tak	Identyfikator odznaki do wystawienia
recipient	object	Tak	Dane odbiorcy (zobacz poniżej)
recipient.name	string	Tak	Imię i nazwisko odbiorcy (minimum 5 znaków)
recipient.email	string	Tak	Adres e-mail odbiorcy
issuedOn	string	Tak	Data wystawienia w formacie ISO 8601 (np. 2025-01-15)
expires	string	Nie	Data ważności w formacie ISO 8601

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ź

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

Uwagi

• Liczy się jako jedno poświadczenie w Twojej rocznej puli poświadczeń (Free: 1200/rok, Starter: 12 000/rok, Pro: 120 000/rok). Pula to elastyczny roczny limit — wykorzystuj go, kiedy chcesz w ciągu roku, także w seriach — i odnawia się w rocznicę rejestracji konta. Rozliczenia nadal są miesięczne; tylko limit poświadczeń jest roczny. Szczegóły znajdziesz w Plany i rozliczenia.

---

Lista poświadczeń

Pobiera poświadczenia z opcjonalnym filtrowaniem i paginacją.

GET /awards

Parametry zapytania

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

Obiekt filtra

Parametr filter przyjmuje ciąg JSON z następującymi polami:

Pole	Typ	Opis
badgeId	string	Filtruje według identyfikatora odznaki.
search	string	Fragment do wyszukania w imionach i nazwiskach lub adresach e-mail odbiorców (zobacz searchField).
searchField	string	name (domyślnie) lub email — w której kolumnie szukać.

Paginacja za pomocą lastEvaluatedKey działa z filtrami i bez nich. Rozmiar strony to 50.

Przykład — lista wszystkich poświadczeń

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

Przykład — filtrowanie według odznaki

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ź

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

Jeśli w odpowiedzi występuje lastEvaluatedKey, są kolejne wyniki. Przekaż go jako parametr zapytania w następnym żądaniu, aby pobrać kolejną stronę.

---

Wyślij e-mail z poświadczeniem

Wysyła odbiorcy powiadomienie e-mail o jego poświadczeniu.

POST /awards/{awardId}/send

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator poświadczenia (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ź

Zwraca prosty ciąg potwierdzenia:

"email sent"

---

Udostępnij poświadczenie

Udostępnia poświadczenie e-mailem wielu odbiorcom.

POST /awards/{awardId}/share

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator poświadczenia (parametr ścieżki i treści)
recipients	string	Tak	Lista adresów e-mail oddzielonych przecinkami
subject	string	Tak	Temat e-maila
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ź

Zwraca prosty ciąg potwierdzenia:

"email sent"

---

Unieważnij poświadczenie

Unieważnia poświadczenie, które wystawiłeś. Hostowana assertion Open Badges v2.0 jest oznaczana jako revoked: true (z opcjonalnym powodem), dzięki czemu każdy weryfikator widzi, że odznaka nie jest już ważna. Rekord poświadczenia jest zachowywany do celów audytu, a kredyt nie jest zwracany.

Unieważnienie propaguje się również do Verifiable Credential Open Badges 3.0 tego poświadczenia: bit poświadczenia jest przełączany w W3C Bitstring Status List wskazanej przez credentialStatus w VC, więc portfele VC także je wykrywają. Zobacz Unieważnianie (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator poświadczenia (parametr ścieżki)
reason	string	Nie	Powód unieważnienia. Obcinany do 500 znaków.
notify	boolean	Nie	Gdy true, wysyła odbiorcy e-mail z informacją o unieważnieniu poświadczenia. Domyślnie false.

Przykład

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

Odpowiedź

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

Unieważnienie już unieważnionego poświadczenia jest idempotentne — zwraca tę samą odpowiedź bez ponownego wysyłania powiadomienia.

Unieważnianie zbiorcze

Aby unieważnić wiele poświadczeń naraz, użyj trwałego endpointu zbiorczego z action: "revoke" zamiast wywoływać ten endpoint dla każdego poświadczenia osobno:

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

Zwraca { "jobId", "total" }; zadanie unieważnia każdy identyfikator po stronie serwera (pomijając już unieważnione) i można je wznowić. Identyfikatory już unieważnione oraz nieistniejące są raportowane jako pominięte.

---

Usuń poświadczenie

Trwale usuwa poświadczenie, które wystawiłeś. W przeciwieństwie do unieważnienia, całkowicie usuwa rekord, a publiczna strona poświadczenia zwraca 404. Używaj tego w przypadku faktycznych pomyłek (np. wystawienie niewłaściwej osobie); w przypadku prawdziwych poświadczeń wybieraj unieważnienie, aby assertion pozostała weryfikowalna jako unieważniona. Kredyt nie jest zwracany.

DELETE /awards/{awardId}

Parametry

Parametr	Typ	Wymagany	Opis
awardId	string	Tak	Identyfikator poświadczenia (parametr ścieżki)

Przykład

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

Odpowiedź

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

---

Pobierz certyfikat PDF

Generuje gotowy do wydruku certyfikat PDF w formacie A4 dla poświadczenia.

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

Nie wymaga uwierzytelnienia — ten endpoint jest publiczny, aby odbiorcy mogli pobrać własny certyfikat.

Przykład

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

Odpowiedzią jest binarny plik PDF z nagłówkiem Content-Type: application/pdf.

---

Zarejestruj zdarzenie poświadczenia

Rejestruje zdarzenie zaangażowania. Używane przez publiczną stronę poświadczenia do zasilania statystyk zaangażowania. Nie wymaga uwierzytelnienia.

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

Parametry

Ten endpoint odczytuje treść żądania bezpośrednio (bez wrappera parameters).

Parametr	Typ	Wymagany	Opis
event	string	Tak	Jedno z: view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nie	Gdy event=share, sieć społecznościowa: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Eliminacja duplikatów według IP: to samo zdarzenie z tego samego adresu IP jest liczone raz na 24 godziny.

Przykład

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

Odpowiedź

{
  "ok": true
}

---

Pobierz statystyki poświadczenia

Pobiera skumulowane liczniki zaangażowania dla poświadczenia.

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

Nie wymaga uwierzytelnienia.

Odpowiedź

Liczniki są zwracane według surowego typu zdarzenia. totals zawiera łączną liczbę dla każdego zdarzenia; networks pokazuje podział na sieci dla zdarzeń zawierających network (obecnie share). Zdarzenia bez zarejestrowanej aktywności po prostu nie występują.

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