Pengesahan Awam

Titik akhir ini adalah awam dan tidak memerlukan pengesahan identiti (autentikasi). Ia membolehkan sesiapa sahaja mengesahkan kelayakan lencana dan mendapatkan data JSON Open Badge v2.0.

Semua titik akhir adalah relatif kepada https://api.badges.ninja.

Get Issuer

Dapatkan JSON Profil Pengeluar (Issuer Profile) Open Badge v2.0 bagi pengeluar tertentu.

GET /certify-badge/issuer/{guid}

Contoh

curl https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Respons

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Issuer",
  "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "name": "Acme Academy",
  "url": "https://acme.example.com",
  "email": "badges@acme.example.com",
  "verification": {
    "type": "hosted",
    "allowedOrigins": "api.badges.ninja"
  }
}

---

Get Badge

Dapatkan JSON BadgeClass Open Badge v2.0 bagi lencana tertentu.

GET /certify-badge/badge/{guid}

Contoh

curl https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901

Respons

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "BadgeClass",
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": {
    "narrative": "Completed the JavaScript Fundamentals course with a score of 80% or higher"
  },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-..."
}

---

Get Credential

Dapatkan JSON Assertion Open Badge v2.0 bagi kelayakan tertentu.

GET /certify-badge/award/{guid}

Contoh

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

Respons

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
  "recipient": {
    "type": "email",
    "hashed": true,
    "identity": "sha256$..."
  },
  "badge": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "issuedOn": "2025-01-15T00:00:00.000Z",
  "verification": {
    "type": "hosted"
  },
  "revoked": false
}

Jika kelayakan telah dibatalkan, assertion akan mengandungi "revoked": true dan, apabila sebab diberikan, rentetan "revocationReason":

{
  "revoked": true,
  "revocationReason": "Issued in error"
}

Ini ialah paparan pembatalan menurut Open Badges 2.0. Pembatalan yang sama turut dinyatakan dalam Verifiable Credential Open Badges 3.0 bagi kelayakan tersebut — lihat Pembatalan (Bitstring Status List).

Nota

• E-mel penerima di-hash (SHA-256) untuk privasi, mengikut spesifikasi Open Badge.
• Respons disimpan dalam cache selama 5 minit (Cache-Control: public, max-age=300). Kelayakan yang dibatalkan menggunakan cache yang lebih singkat iaitu 30 saat (max-age=30) supaya pembatalan tersebar dengan cepat.

---

Get Credential Share Text

Dapatkan teks perkongsian tersuai bagi lencana sesuatu kelayakan.

GET /certify-badge/award/{guid}/share-text

Contoh

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

Respons

{
  "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
}

Jika tiada teks perkongsian tersuai ditetapkan, mesej lalai akan dipulangkan.

---

Send Credential Email (Public)

Hantar e-mel pemberitahuan kelayakan daripada titik akhir awam. Ini digunakan oleh halaman perkongsian awam.

POST /certify-badge/award/{guid}/send-email

Parameter

Parameter	Jenis	Diperlukan	Penerangan
recipients	string	Ya	Senarai alamat e-mel dipisahkan dengan koma
message	string	Tidak	Mesej tersuai untuk disertakan dalam e-mel

Contoh

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "recipients": "colleague@example.com",
      "message": "Check out this badge!"
    }
  }'

Respons

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

Ini ialah satu-satunya titik akhir yang membungkus hasilnya dalam sampul { "statusCode", "info" }. Setiap titik akhir lain memulangkan muatannya secara terus.

---

Verify Issuer

Sahkan pengeluar dengan mengklik pautan pengesahan yang dihantar ke e-mel pengeluar. Ini biasanya diakses melalui pautan dalam e-mel pengesahan, bukan dipanggil secara langsung.

GET /certify-badge/verify-issuer/{guid}/{code}

Parameter

Parameter	Jenis	Penerangan
guid	string	GUID pengeluar
code	string	Kod pengesahan

Respons

Memulangkan halaman HTML yang mengesahkan sama ada pengesahan berjaya atau gagal. Titik akhir ini direka untuk dibuka dalam pelayar.