Menerbitkan Open Badges lewat REST API Badges Ninja: Panduan Cepat

Sebagian besar program kredensial sebenarnya tidak membutuhkan API. Jika Anda menjalankan kursus dengan beberapa ratus lulusan per tahun, dasbor sudah cukup untuk semuanya: Anda merancang lencana di perancang visual, mengunggah CSV, dan setiap penerima mendapatkan halaman verifikasi serta sertifikat PDF. Jika itu situasi Anda, mulailah dengan cara menerbitkan Open Badges dari CSV dan kembali lagi nanti.

API baru berguna ketika kredensial harus diterbitkan oleh sistem lain: platform pembelajaran Anda menandai kursus selesai, alat pendaftaran menutup sebuah acara, sistem HR mencatat modul kepatuhan yang rampung. Dalam kasus seperti itu tidak ada yang mau mengekspor spreadsheet setiap akhir pekan. Satu panggilan HTTP saat penyelesaian jauh lebih sederhana, dan penerima mendapatkan lencananya selagi pencapaiannya masih segar.

Panduan cepat ini menelusuri seluruh alurnya dalam empat panggilan: dapatkan kunci, buat penerbit, buat lencana, lalu berikan. Setelah itu kita lihat cara menyerahkan tautan verifikasi kepada penerima dan memeriksa hasilnya. Setiap bentuk permintaan di bawah ini berasal dari handler yang sudah dideploy, jadi Anda bisa langsung menempel dan menjalankannya.

Yang Anda butuhkan sebelum mulai

• Akun gratis di badges.ninja. Paket Free sudah cukup untuk tutorial ini: mencakup 2 penerbit, 5 lencana, 2 seat, dan 1 kunci API.
• Satu kunci API, dibuat dari dasbor.
• Berkas PNG atau JPG untuk gambar lencana, atau lencana yang Anda rancang di perancang visual.

URL dasar untuk semuanya adalah https://api.badges.ninja.

Langkah 1: Buat kunci API

Masuk, buka API Keys di bilah samping, lalu klik Create API Key. Beri nama yang menunjukkan di mana kunci itu akan dipakai, misalnya “LMS integration”, agar Anda bisa membedakan kunci saat merotasinya nanti.

Kunci hanya ditampilkan satu kali. Segera salin ke secrets manager atau variabel lingkungan Anda. Kunci berbentuk bws_ diikuti 32 karakter heksadesimal, dan Anda mengirimnya di header X-Api-Key pada setiap permintaan. Mencabut kunci dari layar yang sama berlaku seketika.

Beberapa kebiasaan yang menghemat masalah di kemudian hari:

• Jangan pernah menaruh kunci di kode front-end atau repositori publik. Panggil API dari server, fungsi serverless, atau alat otomasi.
• Gunakan satu kunci per integrasi. Jika satu bocor, Anda hanya mencabut satu integrasi, bukan semuanya.
• Dasbor juga menerima sesi masuk Anda (JWT Cognito yang dikirim sebagai Authorization: Bearer), tetapi untuk skrip dan integrasi, kunci API adalah alat yang tepat.

Semua contoh di bawah membaca kunci dari variabel lingkungan bernama BADGES_API_KEY.

Langkah 2: Buat penerbit

Penerbit adalah organisasi yang berdiri di belakang lencana. Namanya muncul di setiap halaman verifikasi dan di dalam data Open Badge v2.0, jadi gunakan nama yang benar-benar dikenal orang.

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

Kolom wajibnya adalah name (minimal 3 karakter), url (alamat http atau https yang valid), dan email. Kolom opsionalnya adalah logo (gambar berenkode base64) dan linkedinOrganizationId, yang mengaktifkan tombol Add to LinkedIn Profile di halaman kredensial publik Anda.

Responsnya berisi pengenal penerbit:

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

Simpan nilai itu persis seperti yang dikembalikan. Nilai tersebut menjadi masukan untuk langkah berikutnya.

Verifikasi penerbit

Lencana hanya dapat dibuat di bawah penerbit yang terverifikasi. Verifikasi bekerja seperti ini:

• Jika email penerbit sama dengan email akun Anda, penerbit diverifikasi secara otomatis. Ini jalur tercepat untuk uji coba pertama.
• Jika emailnya berbeda, email verifikasi berisi kode dikirim ke alamat tersebut. Anda mengonfirmasi kode itu di dasbor (atau lewat API penerbit) sebelum membuat lencana.

Jadi untuk tutorial ini, gunakan email yang sama dengan yang Anda pakai saat mendaftar.

Langkah 3: Buat lencana

Lencana adalah templat yang dapat dipakai ulang: nama, deskripsi, kriteria, dan gambar. Setiap penghargaan yang Anda terbitkan nanti merujuk kembali ke templat ini.

Permintaannya berupa JSON biasa. Gambar dikirim sebagai string base64, jadi tidak ada unggahan multipart yang merepotkan. Awalan data URL seperti data:image/png;base64, diterima dan akan dibuang.

JavaScript (Node 18 atau lebih baru):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Kelima kolom (name, description, criteria, image, issuerId) wajib diisi. Ada dua kolom opsional yang perlu diketahui: shareText, teks bawaan yang dilihat penerima saat berbagi di jejaring sosial (mendukung placeholder {{badge_name}}, {{issuer_name}}, dan {{award_url}}), serta designJson, yang menyimpan dokumen perancang visual agar lencana bisa diedit lapisan demi lapisan nanti.

Respons sukses adalah HTTP 200 dengan { "badgeId": "<id>" }. Gambar disimpan secara permanen, dan lencana kini menjadi BadgeClass Open Badge v2.0 yang dapat diambil siapa saja.

Haruskah lencana dibuat lewat kode?

Biasanya tidak. Merancang lencana adalah pekerjaan kreatif, dan perancang visual (80+ templat, bentuk, ikon, 11 font, dan unggahan kustom) adalah tempat yang jauh lebih baik daripada skrip. Pola yang umum: rancang setiap lencana sekali di dasbor, lalu integrasi Anda hanya menerbitkan penghargaan terhadapnya. Anda dapat melihat daftar lencana dengan GET /badges dan menyalin id lencana yang Anda inginkan.

Buat lencana lewat API ketika Anda membuatnya secara terprogram, misalnya satu per kursus dalam katalog ratusan kursus, atau ketika Anda mengisi lingkungan pengujian.

Langkah 4: Berikan lencana

Inilah panggilan yang akan dilakukan integrasi Anda ribuan kali. Kirim lencana, penerima, dan tanggalnya.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Aturan yang sering membuat orang tersandung:

• recipient adalah objek bersarang dengan name dan email. Kolom datar seperti recipientEmail ditolak.
• recipient.name minimal 5 karakter.
• issuedOn wajib diisi. Kirim epoch milidetik atau string tanggal ISO seperti 2026-09-28.
• expires bersifat opsional dan menerima format yang sama.

Respons sukses adalah HTTP 200 dengan isi yang memuat awardId. Email penerima disimpan sebagai hash SHA-256 dalam data Open Badge, sehingga JSON publik tidak pernah mengungkapkannya.

Langkah 5: Temukan halaman verifikasi dan JSON Open Badge

Respons penghargaan memberi Anda sebuah pengenal, bukan tautan siap pakai. Pengenal itu diakhiri dengan GUID, dan halaman publik dibangun dari GUID tersebut:

• Halaman verifikasi yang mudah dibaca: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Jika awardId Anda berupa URL lengkap, gunakan segmen path terakhir sebagai GUID.

Keduanya bersifat publik. Siapa pun yang memiliki tautan dapat memverifikasi kredensial tanpa membuat akun, dan itulah intinya: pemberi kerja atau petugas penerimaan mahasiswa harus bisa memeriksa lencana dalam sepuluh detik.

Ambil JSON-nya untuk melihat apa yang dilihat dunia:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Anda mendapatkan Assertion Open Badge v2.0: lencana yang dirujuk, identitas penerima yang di-hash, tanggal penerbitan, dan blok verifikasi yang menunjuk kembali ke assertion yang di-host. Karena ini data Open Badges standar, alat apa pun yang memahami formatnya dapat membacanya. Portabilitas itulah alasan memilih Open Badges ketimbang PDF proprietari; Open Badges vs sertifikat PDF membahas pertimbangan ini lebih dalam.

Bagaimana penerima menerima kredensial

Membuat penghargaan berbeda dari memberi tahu penerimanya. Penerima dapat membuka kredensial mereka lewat portal penerima di badges.ninja/me, yang memakai masuk dengan magic link tanpa kata sandi, dan mereka dapat memublikasikan profil publik di badges.ninja/u/<handle>. Dari halaman verifikasi, mereka dapat menambahkan lencana ke LinkedIn, mengunduh sertifikat PDF, atau membagikan tautannya.

Untuk beberapa uji coba pertama, kirim penghargaan ke alamat email Anda sendiri dan jalani pengalaman sebagai penerima. Ini cara tercepat untuk menyadari hal-hal seperti deskripsi lencana yang terdengar janggal.

Penanganan error yang tidak menyakitkan

API memakai kode status HTTP biasa. Yang akan Anda temui:

Dua tips praktis. Pertama, perlakukan 400 sebagai masalah data dan catat isi responsnya, karena di dalamnya disebutkan kolom yang gagal. Kedua, jadikan integrasi Anda idempoten di sisi Anda: simpan awardId di samping catatan penyelesaian pada basis data Anda sendiri, dan periksa keberadaannya sebelum memanggil API lagi. Dengan begitu webhook yang dikirim ulang atau job yang dijalankan ulang tidak akan menerbitkan dua kredensial untuk orang yang sama.

Menyatukan semuanya dalam integrasi nyata

Rangkaian yang umum terlihat seperti ini:

1. Rancang lencana di dasbor, satu per kursus atau tonggak, dan catat ID setiap lencana.
2. Simpan pemetaan dari kursus ke ID lencana di sistem Anda.
3. Ketika peserta didik menyelesaikan kursus, server Anda memanggil POST /awards dengan nama, email, dan tanggal penyelesaiannya.
4. Simpan awardId yang dikembalikan pada catatan penyelesaian.
5. Tampilkan tautan verifikasi di dalam produk Anda sendiri, sehingga peserta didik melihatnya tanpa harus keluar.

Jika Anda lebih suka tidak menulis kode, panggilan yang sama berfungsi dari alat otomasi apa pun yang dapat mengirim permintaan HTTP dengan isi JSON dan header kustom. Arahkan ke https://api.badges.ninja/awards dan petakan kolom formulir atau spreadsheet Anda ke badgeId, recipient.name, recipient.email, dan issuedOn.

Paket dan batasan yang perlu diketahui

API tersedia di setiap paket; Anda tidak perlu membayar tambahan untuk membukanya. Paket Free ($0) mencakup 2 penerbit, 5 lencana, 2 seat, 1 kunci API, dan 1.200 kredensial per tahun. Starter seharga $9 per bulan dan Pro $29 per bulan, dengan batas yang lebih tinggi. Periksa halaman harga untuk angka terbaru sebelum Anda menghitung skala peluncuran. Jika Anda membandingkan biaya akses API di platform lain, Credly alternative memaparkan biayanya berdampingan.

Langkah selanjutnya

• Referensi endpoint lengkap ada di dokumentasi API, tersedia dalam 40 bahasa.
• Untuk detail autentikasi dan penanganan kunci, lihat panduan autentikasi.
• Untuk kode error secara mendalam, lihat referensi error.
• Ketika satu panggilan sekaligus tidak lagi cukup, gunakan penghargaan massal di dasbor: unggah CSV, dan jeda atau lanjutkan proses jika perlu.

Penghargaan pertama yang berhasil adalah bagian tersulit. Setelah itu, sisanya hanyalah memasang panggilan yang sama di tempat-tempat yang sudah mencatat pencapaian.

Siap menerbitkan kredensial terverifikasi pertama Anda? Mulai gratis di badges.ninja — perancang visual, halaman verifikasi publik, sertifikat PDF, keluaran Open Badge v2.0. Tanpa kartu kredit.