API Penerbit

Kelola penerbit lencana — organisasi atau individu yang menerbitkan lencana.

Semua endpoint memerlukan autentikasi melalui header X-Api-Key. Lihat Autentikasi.

Buat Penerbit

Buat penerbit lencana baru.

POST /issuers

Parameter

Parameter	Tipe	Wajib	Deskripsi
name	string	Ya	Nama organisasi (minimal 3 karakter)
url	string	Ya	Situs web organisasi (harus berupa URL HTTP/HTTPS yang valid)
email	string	Ya	Email kontak untuk penerbit
logo	string	Tidak	Gambar berenkode Base64 (PNG atau JPG)
linkedinOrganizationId	string	Tidak	ID numerik halaman perusahaan LinkedIn. Jika diisi, setiap halaman kredensial publik dari penerbit ini menampilkan tombol Add to LinkedIn Profile.

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

Catatan

• Dihitung terhadap batas penerbit paket Anda (Free: 2, Starter: 5, Pro: 10). Tidak ada pemotongan kuota.
• Jika email penerbit sama dengan email akun Anda, penerbit diverifikasi secara otomatis.
• Jika emailnya berbeda, email verifikasi dikirim ke email penerbit.
• Setelah mengonfigurasi penerbit, gunakan API Kredensial untuk mulai menerbitkan kredensial atas nama penerbit tersebut.

---

Daftar Penerbit

Ambil semua penerbit yang telah Anda buat.

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 adalah Unix epoch dalam milidetik. Jika jumlah penerbit melebihi satu halaman, lastEvaluatedKey juga dikembalikan untuk paginasi.

---

Verifikasi Penerbit

Verifikasi penerbit menggunakan kode verifikasi yang dikirim ke emailnya.

POST /issuers/{issuerId}/verify

Parameter

Parameter	Tipe	Wajib	Deskripsi
issuerId	string	Ya	ID penerbit (parameter path)
code	string	Ya	Kode verifikasi dari email

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

String tunggal:

"issuer has been verified"

---

Hapus Penerbit

Hapus penerbit. Penerbit tidak boleh memiliki lencana yang terhubung.

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

String tunggal:

"issuer has been deleted"

Kesalahan

• 400 — penerbit masih memiliki lencana yang terhubung: issuer has {n} badge(s) linked — delete the badges first. Penghapusan hanya dibatasi oleh lencana yang terhubung — kredensial tidak menghalanginya.
• 404 — penerbit tidak ditemukan

---

Perbarui Penerbit

Perbarui kolom penerbit. Hanya penerbit yang belum diverifikasi yang dapat diedit — setelah penerbit diverifikasi, endpoint ini mengembalikan 400 verified issuers cannot be edited untuk menjaga stabilitas kredensial. Mengedit penerbit akan membuat ulang kode verifikasinya: jika email sama dengan email akun Anda, penerbit diverifikasi ulang secara otomatis; jika tidak, email verifikasi baru dikirim ke alamat tersebut.

PUT /issuers/{issuerId}

Parameter

Parameter	Tipe	Wajib	Deskripsi
issuerId	string	Ya	ID penerbit (parameter path)
name	string	Tidak	Nama baru
url	string	Tidak	URL baru
email	string	Tidak	Email baru (mengirim email verifikasi baru kecuali sama dengan email akun Anda)
logo	string	Tidak	Logo baru berenkode base64
linkedinOrganizationId	string	Tidak	ID organisasi LinkedIn baru (atau string kosong untuk menghapus)

Respons

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

Kesalahan

• 400 — verified issuers cannot be edited (penerbit sudah diverifikasi)
• 400 — not authorized (penerbit milik akun lain)
• 404 — penerbit tidak ditemukan