API Kredensial

Cipta dan urus kredensial (assertion) — lencana yang dikeluarkan kepada penerima tertentu.

Semua endpoint memerlukan pengesahan melalui pengepala X-Api-Key. Lihat Pengesahan.

Cipta Kredensial

Keluarkan lencana kepada seorang penerima.

Perlu mengeluarkan kepada ratusan atau ribuan penerima sekaligus dan bukannya satu panggilan API bagi setiap orang? Gunakan ciri UI Kredensial Pukal, yang menerima muat naik CSV.

POST /awards

Parameter

Parameter	Jenis	Diperlukan	Perihalan
badgeId	string	Ya	ID lencana yang akan dikeluarkan
recipient	object	Ya	Butiran penerima (lihat di bawah)
recipient.name	string	Ya	Nama penuh penerima (minimum 5 aksara)
recipient.email	string	Ya	Alamat e-mel penerima
issuedOn	string	Ya	Tarikh pengeluaran dalam format ISO 8601 (cth. 2025-01-15)
expires	string	Tidak	Tarikh luput dalam format ISO 8601

Contoh

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

Respons

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

Nota

• Dikira sebagai satu kredensial daripada kolam kredensial tahunan anda (Free: 1,200/tahun, Starter: 12,000/tahun, Pro: 120,000/tahun). Kolam ini ialah peruntukan tahunan yang fleksibel — gunakan bila-bila masa sepanjang tahun, termasuk secara berkelompok — dan ditetapkan semula pada ulang tahun pendaftaran akaun anda. Pengebilan kekal bulanan; hanya kuota kredensial yang tahunan. Lihat Pelan & Pengebilan untuk butiran.

---

Senaraikan Kredensial

Dapatkan kredensial dengan penapisan dan penomboran halaman pilihan.

GET /awards

Parameter Pertanyaan

Parameter	Jenis	Diperlukan	Perihalan
filter	JSON string	Tidak	Objek penapis (lihat di bawah)
lastEvaluatedKey	string	Tidak	Token penomboran halaman daripada respons sebelumnya

Objek Penapis

Parameter filter menerima rentetan JSON dengan medan berikut:

Medan	Jenis	Perihalan
badgeId	string	Tapis mengikut ID lencana.
search	string	Subrentetan untuk dicari dalam nama atau e-mel penerima (lihat searchField).
searchField	string	Sama ada name (lalai) atau email — lajur yang dicari.

Penomboran halaman melalui lastEvaluatedKey berfungsi dengan atau tanpa penapis. Saiz halaman ialah 50.

Contoh — Senaraikan Semua Kredensial

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

Contoh — Tapis mengikut Lencana

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"

Respons

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

Jika lastEvaluatedKey terdapat dalam respons, masih ada lebih banyak hasil. Hantarkannya sebagai parameter pertanyaan dalam permintaan seterusnya untuk mendapatkan halaman berikutnya.

---

Hantar E-mel Kredensial

Hantar pemberitahuan e-mel kepada penerima tentang kredensial mereka.

POST /awards/{awardId}/send

Parameter

Parameter	Jenis	Diperlukan	Perihalan
awardId	string	Ya	ID anugerah (parameter laluan dan badan)
email	string	Ya	Alamat e-mel penerima

Contoh

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

Respons

Mengembalikan rentetan pengesahan biasa:

"email sent"

---

Kongsi Kredensial

Kongsi kredensial dengan beberapa penerima melalui e-mel.

POST /awards/{awardId}/share

Parameter

Parameter	Jenis	Diperlukan	Perihalan
awardId	string	Ya	ID anugerah (parameter laluan dan badan)
recipients	string	Ya	Senarai alamat e-mel dipisahkan koma
subject	string	Ya	Baris subjek e-mel
message	string	Ya	Kandungan mesej e-mel

Contoh

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

Respons

Mengembalikan rentetan pengesahan biasa:

"email sent"

---

Batalkan Kredensial

Batalkan kredensial yang anda keluarkan. Assertion Open Badges v2.0 yang dihoskan ditandakan revoked: true (dengan sebab pilihan) supaya mana-mana pengesah nampak bahawa lencana tidak lagi sah. Rekod kredensial disimpan untuk tujuan audit, dan tiada kredit dikembalikan.

Pembatalan turut merebak ke Verifiable Credential Open Badges 3.0 bagi kredensial tersebut: bit anugerah itu diterbalikkan dalam Bitstring Status List W3C yang dirujuk oleh credentialStatus VC, jadi dompet VC turut mengesannya. Lihat Pembatalan (Bitstring Status List).

POST /awards/{awardId}/revoke

Parameter

Parameter	Jenis	Diperlukan	Perihalan
awardId	string	Ya	ID anugerah (parameter laluan)
reason	string	Tidak	Sebab pembatalan. Dipotong kepada 500 aksara.
notify	boolean	Tidak	Apabila true, e-mel dihantar kepada penerima bahawa kredensial mereka telah dibatalkan. Lalai false.

Contoh

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

Respons

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

Membatalkan kredensial yang sudah dibatalkan bersifat idempoten — ia mengembalikan respons yang sama tanpa menghantar semula pemberitahuan.

Batalkan secara pukal

Untuk membatalkan banyak kredensial sekaligus, gunakan endpoint pukal tahan lasak dengan action: "revoke" dan bukannya memanggil endpoint ini bagi setiap anugerah:

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

Ia mengembalikan { "jobId", "total" }; tugasan membatalkan setiap id di bahagian pelayan (melangkau yang sudah dibatalkan) dan boleh disambung semula. ID yang sudah dibatalkan dan yang tidak wujud dilaporkan sebagai dilangkau.

---

Padam Kredensial

Padam kekal kredensial yang anda keluarkan. Tidak seperti pembatalan, ini membuang rekod sepenuhnya dan halaman kredensial awam akan mengembalikan 404. Gunakan ini untuk kesilapan sebenar (cth. dikeluarkan kepada orang yang salah); utamakan pembatalan untuk kredensial sebenar supaya assertion kekal boleh disahkan sebagai dibatalkan. Tiada kredit dikembalikan.

DELETE /awards/{awardId}

Parameter

Parameter	Jenis	Diperlukan	Perihalan
awardId	string	Ya	ID anugerah (parameter laluan)

Contoh

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

Respons

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

---

Muat Turun Sijil PDF

Jana sijil PDF A4 siap cetak untuk sesuatu kredensial.

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

Tiada pengesahan diperlukan — endpoint ini awam supaya penerima boleh memuat turun sijil mereka sendiri.

Contoh

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

Respons ialah PDF binari dengan pengepala Content-Type: application/pdf.

---

Jejak Peristiwa Kredensial

Rekod peristiwa penglibatan. Digunakan oleh halaman kredensial awam untuk mengisi statistik penglibatan. Tiada pengesahan diperlukan.

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

Parameter

Endpoint ini membaca badannya secara langsung (tanpa pembungkus parameters).

Parameter	Jenis	Diperlukan	Perihalan
event	string	Ya	Salah satu daripada view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Tidak	Apabila event=share, rangkaian sosial: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Penindasan pendua bagi setiap IP: peristiwa yang sama daripada IP yang sama dikira sekali setiap 24 jam.

Contoh

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

Respons

{
  "ok": true
}

---

Dapatkan Statistik Kredensial

Dapatkan kaunter penglibatan kumulatif bagi sesuatu kredensial.

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

Tiada pengesahan diperlukan.

Respons

Kaunter dikembalikan mengikut jenis peristiwa mentah. totals menyimpan jumlah bilangan bagi setiap peristiwa; networks memecahkan pembahagian setiap rangkaian bagi peristiwa yang membawa network (buat masa ini share). Peristiwa tanpa aktiviti yang direkodkan tidak disertakan.

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