API Pengeluar

Urus pengeluar lencana — organisasi atau individu yang mengeluarkan lencana.

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

Cipta Pengeluar

Cipta pengeluar lencana baharu.

POST /issuers

Parameter

Parameter	Jenis	Wajib	Penerangan
name	string	Ya	Nama organisasi (minimum 3 aksara)
url	string	Ya	Laman web organisasi (mestilah URL HTTP/HTTPS yang sah)
email	string	Ya	E-mel hubungan untuk pengeluar
logo	string	Tidak	Imej berkod Base64 (PNG atau JPG)
linkedinOrganizationId	string	Tidak	ID berangka halaman syarikat LinkedIn. Apabila ditetapkan, setiap halaman kredensial awam daripada pengeluar ini memaparkan butang Tambah ke Profil LinkedIn.

Contoh

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Respons

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Nota

• Dikira dalam had pengeluar pelan anda (Free: 2, Starter: 5, Pro: 10). Tiada penolakan kuota.
• Jika e-mel pengeluar sepadan dengan e-mel akaun anda, pengeluar disahkan secara automatik.
• Jika e-mel berbeza, e-mel pengesahan dihantar ke e-mel pengeluar.
• Selepas mengkonfigurasi pengeluar, gunakan API Kredensial untuk mula mengeluarkan kredensial di bawah pengeluar tersebut.

---

Senaraikan Pengeluar

Dapatkan semua pengeluar yang telah anda cipta.

GET /issuers

Contoh

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

Respons

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp ialah epok Unix dalam milisaat. Apabila terdapat lebih banyak pengeluar daripada yang muat dalam satu halaman, lastEvaluatedKey turut dikembalikan untuk penomboran halaman.

---

Sahkan Pengeluar

Sahkan pengeluar menggunakan kod pengesahan yang dihantar ke e-melnya.

POST /issuers/{issuerId}/verify

Parameter

Parameter	Jenis	Wajib	Penerangan
issuerId	string	Ya	ID pengeluar (parameter laluan)
code	string	Ya	Kod pengesahan daripada e-mel

Contoh

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Respons

Rentetan kosong (bare string):

"issuer has been verified"

---

Padam Pengeluar

Padam pengeluar. Pengeluar tidak boleh mempunyai sebarang lencana yang dipautkan kepadanya.

DELETE /issuers/{issuerId}

Contoh

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Respons

Rentetan kosong (bare string):

"issuer has been deleted"

Ralat

• 400 — pengeluar masih mempunyai lencana yang dipautkan kepadanya: issuer has {n} badge(s) linked — delete the badges first. Pemadaman hanya disekat oleh lencana yang dipautkan — kredensial tidak menyekatnya.
• 404 — pengeluar tidak ditemui

---

Kemas Kini Pengeluar

Kemas kini medan pengeluar. Hanya pengeluar yang belum disahkan boleh disunting — setelah pengeluar disahkan, endpoint ini mengembalikan 400 verified issuers cannot be edited bagi mengekalkan kestabilan kredensial. Menyunting pengeluar menjana semula kod pengesahannya: jika email sepadan dengan e-mel akaun anda, pengeluar disahkan semula secara automatik, jika tidak e-mel pengesahan baharu dihantar ke alamat tersebut.

PUT /issuers/{issuerId}

Parameter

Parameter	Jenis	Wajib	Penerangan
issuerId	string	Ya	ID pengeluar (parameter laluan)
name	string	Tidak	Nama baharu
url	string	Tidak	URL baharu
email	string	Tidak	E-mel baharu (menghantar e-mel pengesahan baharu kecuali sepadan dengan e-mel akaun anda)
logo	string	Tidak	Logo berkod base64 baharu
linkedinOrganizationId	string	Tidak	ID organisasi LinkedIn baharu (atau rentetan kosong untuk mengosongkan)

Respons

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Ralat

• 400 — verified issuers cannot be edited (pengeluar sudah disahkan)
• 400 — not authorized (pengeluar milik akaun lain)
• 404 — pengeluar tidak ditemui