Mengeluarkan Open Badges melalui REST API Badges Ninja: Panduan Pantas

Kebanyakan program kredensial tidak memerlukan API. Jika anda mengendalikan kursus dengan beberapa ratus graduan setahun, papan pemuka melakukan segalanya: anda mereka lencana dalam pereka visual, muat naik CSV, dan setiap penerima mendapat halaman pengesahan serta sijil PDF. Jika itu keadaan anda, mulakan dengan cara mengeluarkan Open Badges daripada CSV dan kembali kemudian.

API membuktikan nilainya apabila kredensial perlu dikeluarkan oleh sistem lain: platform pembelajaran anda menanda kursus selesai, alat pendaftaran anda menutup sesuatu acara, sistem HR anda merekodkan modul pematuhan yang telah tamat. Dalam kes begini, tiada siapa mahu mengeksport hamparan setiap hujung minggu. Satu panggilan HTTP pada saat penyelesaian adalah lebih mudah, dan penerima mendapat lencananya ketika pencapaian itu masih segar.

Panduan pantas ini menelusuri keseluruhan laluan dalam empat panggilan: dapatkan kunci, cipta pengeluar, cipta lencana, anugerahkannya. Kemudian kita lihat cara menyerahkan pautan pengesahan kepada penerima dan menyemak hasilnya. Setiap bentuk permintaan di bawah datang daripada handler yang telah digunakan, jadi anda boleh tampal dan jalankannya.

Apa yang anda perlukan sebelum bermula

• Akaun percuma di badges.ninja. Pelan Free mencukupi untuk tutorial ini: ia merangkumi 2 pengeluar, 5 lencana, 2 kerusi dan 1 kunci API.
• Satu kunci API, dicipta daripada papan pemuka.
• Fail PNG atau JPG untuk imej lencana, atau lencana yang anda reka dalam pereka visual.

URL asas untuk semuanya ialah https://api.badges.ninja.

Langkah 1: Cipta kunci API

Log masuk, buka API Keys di bar sisi, dan klik Create API Key. Beri nama yang menunjukkan di mana ia akan digunakan, seperti “Integrasi LMS”, supaya anda dapat membezakan kunci apabila memutarkannya kemudian.

Kunci dipaparkan sekali sahaja. Salin ia terus ke pengurus rahsia atau pemboleh ubah persekitaran anda. Kunci kelihatan seperti bws_ diikuti 32 aksara heks, dan anda menghantarnya dalam pengepala X-Api-Key pada setiap permintaan. Membatalkan kunci daripada skrin yang sama berkuat kuasa serta-merta.

Beberapa tabiat yang menjimatkan masalah kemudian:

• Jangan sekali-kali letak kunci dalam kod front-end atau repositori awam. Panggil API daripada pelayan, fungsi serverless, atau alat automasi.
• Gunakan satu kunci bagi setiap integrasi. Jika satu bocor, anda batalkan satu integrasi sahaja dan bukan semuanya.
• Papan pemuka juga menerima sesi log masuk anda (JWT Cognito yang dihantar sebagai Authorization: Bearer), tetapi untuk skrip dan integrasi, kunci API ialah alat yang betul.

Semua contoh di bawah membaca kunci daripada pemboleh ubah persekitaran bernama BADGES_API_KEY.

Langkah 2: Cipta pengeluar

Pengeluar ialah organisasi yang menjamin lencana itu. Ia muncul pada setiap halaman pengesahan dan di dalam data Open Badge v2.0, jadi gunakan nama yang benar-benar dikenali 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"}'

Medan wajib ialah name (sekurang-kurangnya 3 aksara), url (alamat http atau https yang sah) dan email. Medan pilihan ialah logo (imej dikodkan base64) dan linkedinOrganizationId, yang mengaktifkan butang Add to LinkedIn Profile pada halaman kredensial awam anda.

Respons mengandungi pengecam pengeluar:

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

Simpan nilai itu tepat seperti yang dikembalikan. Ia ialah input untuk langkah seterusnya.

Pengesahan pengeluar

Lencana hanya boleh dicipta di bawah pengeluar yang telah disahkan. Pengesahan berfungsi seperti ini:

• Jika e-mel pengeluar sepadan dengan e-mel pada akaun anda, pengeluar disahkan secara automatik. Ini laluan terpantas untuk ujian pertama.
• Jika e-mel berbeza, e-mel pengesahan beserta kod dihantar ke alamat itu. Anda mengesahkan kod itu dalam papan pemuka (atau melalui API pengeluar) sebelum mencipta lencana.

Jadi untuk tutorial ini, gunakan e-mel yang sama dengan yang anda daftar.

Langkah 3: Cipta lencana

Lencana ialah templat yang boleh digunakan semula: nama, perihalan, kriteria dan imej. Setiap anugerah yang anda keluarkan kemudian merujuk kembali kepadanya.

Permintaan ialah JSON biasa. Imej dimasukkan sebagai rentetan base64, jadi tiada muat naik multipart yang menyusahkan. Awalan data URL seperti data:image/png;base64, diterima dan dibuang.

JavaScript (Node 18 atau lebih baharu):

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-lima medan (name, description, criteria, image, issuerId) adalah wajib. Dua medan pilihan yang patut diketahui: shareText, teks lalai yang dilihat penerima apabila berkongsi di rangkaian sosial (ia menyokong pemegang tempat {{badge_name}}, {{issuer_name}} dan {{award_url}}), dan designJson, yang menyimpan dokumen pereka visual supaya lencana boleh disunting lapisan demi lapisan kemudian.

Kejayaan memulangkan HTTP 200 dengan { "badgeId": "<id>" }. Imej disimpan secara kekal, dan lencana kini menjadi BadgeClass Open Badge v2.0 yang boleh diambil oleh sesiapa sahaja.

Patutkah anda mencipta lencana dalam kod?

Biasanya tidak. Mereka bentuk lencana ialah tugas kreatif, dan pereka visual (80+ templat, bentuk, ikon, 11 fon dan muat naik tersuai) jauh lebih sesuai untuknya berbanding skrip. Corak lazim ialah mereka setiap lencana sekali dalam papan pemuka, kemudian integrasi anda hanya mengeluarkan anugerah terhadapnya. Anda boleh menyenaraikan lencana dengan GET /badges dan menyalin id lencana yang anda mahu.

Cipta lencana melalui API apabila anda menjanakannya secara pengaturcaraan, contohnya satu bagi setiap kursus dalam katalog beratus-ratus, atau apabila anda menyemai persekitaran ujian.

Langkah 4: Anugerahkan lencana

Inilah panggilan yang akan dibuat integrasi anda beribu-ribu kali. Hantar lencana, penerima, dan tarikh.

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

Peraturan yang sering menyusahkan orang:

• recipient ialah objek bersarang dengan name dan email. Medan rata seperti recipientEmail ditolak.
• recipient.name mestilah sekurang-kurangnya 5 aksara.
• issuedOn adalah wajib. Hantar milisaat epoch atau rentetan tarikh ISO seperti 2026-09-28.
• expires adalah pilihan dan menerima format yang sama.

Kejayaan ialah HTTP 200 dengan badan yang mengandungi awardId. E-mel penerima disimpan sebagai cincangan SHA-256 dalam data Open Badge, jadi JSON awam tidak pernah mendedahkannya.

Langkah 5: Cari halaman pengesahan dan JSON Open Badge

Respons anugerah memberi anda pengecam, bukan pautan siap pakai. Pengecam itu berakhir dengan GUID, dan halaman awam dibina daripada GUID tersebut:

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

Jika awardId anda dikembalikan sebagai URL penuh, gunakan segmen laluan terakhir sebagai GUID.

Kedua-duanya awam. Sesiapa yang memiliki pautan boleh mengesahkan kredensial tanpa mencipta akaun, dan itulah tujuannya: majikan atau pegawai kemasukan perlu dapat menyemak lencana dalam sepuluh saat.

Ambil JSON untuk melihat apa yang dilihat dunia:

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

Anda mendapat Assertion Open Badge v2.0: lencana yang dirujuknya, identiti penerima yang dicincang, tarikh pengeluaran, dan blok pengesahan yang menunjuk kembali kepada assertion yang dihoskan. Oleh kerana ia data Open Badges piawai, mana-mana alat yang memahami format itu boleh membacanya. Kebolehpindahan itulah sebab memilih Open Badges berbanding PDF proprietari; Open Badges vs sijil PDF mengupas pertukaran ini dengan lebih mendalam.

Bagaimana penerima menerima kredensial

Mencipta anugerah adalah berasingan daripada memberitahu penerima tentangnya. Penerima boleh membuka kredensial mereka melalui portal penerima di badges.ninja/me, yang menggunakan log masuk pautan ajaib tanpa kata laluan, dan mereka boleh menerbitkan profil awam di badges.ninja/u/<handle>. Dari halaman pengesahan, mereka boleh menambah lencana ke LinkedIn, memuat turun sijil PDF, atau berkongsi pautan.

Untuk beberapa ujian pertama, hantar anugerah kepada diri sendiri dengan alamat e-mel anda dan lalui pengalaman penerima. Ia cara terpantas untuk perasan perkara seperti perihalan lencana yang terbaca janggal.

Pengendalian ralat yang tidak menyakitkan

API menggunakan kod status HTTP biasa. Yang akan anda temui:

Dua petua praktikal. Pertama, anggap 400 sebagai masalah data dan log badan respons, kerana ia menamakan medan yang gagal. Kedua, jadikan integrasi anda idempoten di pihak anda: simpan awardId bersebelahan rekod penyelesaian dalam pangkalan data anda sendiri, dan semaknya sebelum memanggil API sekali lagi. Dengan cara itu webhook yang dicuba semula atau tugas yang dijalankan semula tidak akan mengeluarkan dua kredensial kepada orang yang sama.

Menggabungkan semuanya dalam integrasi sebenar

Pendawaian biasa kelihatan begini:

1. Reka lencana dalam papan pemuka, satu bagi setiap kursus atau pencapaian, dan catat ID setiap lencana.
2. Simpan pemetaan dalam sistem anda daripada kursus kepada ID lencana.
3. Apabila pelajar menamatkan kursus, pelayan anda memanggil POST /awards dengan nama, e-mel dan tarikh penyelesaian mereka.
4. Simpan awardId yang dikembalikan pada rekod penyelesaian.
5. Tunjukkan pautan pengesahan dalam produk anda sendiri, supaya pelajar melihatnya tanpa meninggalkan produk.

Jika anda tidak mahu menulis kod, panggilan yang sama berfungsi daripada mana-mana alat automasi yang boleh menghantar permintaan HTTP dengan badan JSON dan pengepala tersuai. Halakan ke https://api.badges.ninja/awards dan petakan medan borang atau hamparan anda kepada badgeId, recipient.name, recipient.email dan issuedOn.

Pelan dan had yang patut diketahui

API tersedia pada setiap pelan; anda tidak membayar lebih untuk membukanya. Pelan Free ($0) merangkumi 2 pengeluar, 5 lencana, 2 kerusi, 1 kunci API dan 1,200 kredensial setahun. Starter ialah $9 sebulan dan Pro ialah $29 sebulan, dengan had lebih tinggi. Semak halaman harga untuk angka semasa sebelum anda menentukan saiz pelancaran. Jika anda membandingkan caj platform lain untuk akses API, Credly alternative memaparkan kos secara bersebelahan.

Ke mana seterusnya

• Rujukan endpoint penuh terdapat dalam dokumentasi API, yang tersedia dalam 40 bahasa.
• Untuk butiran pengesahan identiti dan pengendalian kunci, lihat panduan pengesahan identiti.
• Untuk kod ralat dengan lebih mendalam, lihat rujukan ralat.
• Apabila satu panggilan pada satu masa tidak lagi mencukupi, gunakan anugerah pukal dalam papan pemuka: muat naik CSV, dan jeda atau sambung semula larian jika perlu.

Anugerah pertama yang berjaya ialah bahagian yang sukar. Selepas itu, selebihnya hanyalah menyambungkan panggilan yang sama ke tempat-tempat di mana pencapaian sudah pun direkodkan.

Bersedia untuk mengeluarkan kredensial boleh disahkan pertama anda? Mulakan percuma di badges.ninja — pereka visual, halaman pengesahan awam, sijil PDF, output Open Badge v2.0. Tiada kad kredit diperlukan.