Badges Ninja REST API ile Open Badges Verme: Hızlı Başlangıç

Çoğu kimlik bilgisi programının API’ye hiç ihtiyacı olmaz. Yılda birkaç yüz mezunu olan bir kurs yürütüyorsanız, kontrol paneli her şeyi halleder: görsel tasarımcıda bir rozet tasarlarsınız, bir CSV yüklersiniz ve her alıcı bir doğrulama sayfası ile PDF sertifika alır. Durumunuz buysa CSV’den Open Badges nasıl verilir yazısıyla başlayın ve daha sonra buraya dönün.

API, kimlik bilgilerinin başka bir sistem tarafından verilmesi gerektiğinde işe yarar: öğrenme platformunuz bir kursu tamamlandı olarak işaretler, kayıt aracınız bir etkinliği kapatır, İK sisteminiz biten bir uyumluluk modülünü kaydeder. Bu durumlarda kimse her haftanın sonunda bir elektronik tablo dışa aktarmak istemez. Tamamlanma anında yapılan tek bir HTTP çağrısı daha basittir ve alıcı başarısı henüz tazeyken rozetini alır.

Bu hızlı başlangıç tüm yolu dört çağrıda gösterir: anahtar alın, düzenleyici oluşturun, rozet oluşturun, verin. Ardından doğrulama bağlantısını alıcıya nasıl ileteceğinize ve sonucu nasıl kontrol edeceğinize bakarız. Aşağıdaki her istek biçimi yayındaki işleyicilerden gelir, yani kopyalayıp çalıştırabilirsiniz.

Başlamadan önce neye ihtiyacınız var

• badges.ninja’da ücretsiz bir hesap. Bu öğretici için Free planı yeterlidir: 2 düzenleyici, 5 rozet, 2 koltuk ve 1 API anahtarı içerir.
• Kontrol panelinden oluşturulmuş bir API anahtarı.
• Rozet görseli için bir PNG veya JPG ya da görsel tasarımcıda tasarladığınız bir rozet.

Her şey için temel URL https://api.badges.ninja adresidir.

Adım 1: Bir API anahtarı oluşturun

Oturum açın, kenar çubuğundan API Keys bölümünü açın ve Create API Key düğmesine tıklayın. Anahtara nerede kullanılacağını anlatan bir ad verin, örneğin “LMS integration”; böylece sonra döndürürken anahtarları birbirinden ayırabilirsiniz.

Anahtar yalnızca bir kez gösterilir. Hemen sır yöneticinize veya bir ortam değişkenine kopyalayın. Anahtarlar bws_ ve ardından 32 onaltılık karakterden oluşur ve her istekte X-Api-Key başlığıyla gönderirsiniz. Aynı ekrandan bir anahtarı iptal etmek anında etkili olur.

Sonradan başınızı ağrıtmayacak birkaç alışkanlık:

• Anahtarı asla ön yüz koduna veya herkese açık bir depoya koymayın. API’yi bir sunucudan, sunucusuz bir fonksiyondan veya bir otomasyon aracından çağırın.
• Entegrasyon başına bir anahtar kullanın. Biri sızarsa hepsini değil, yalnızca bir entegrasyonu iptal edersiniz.
• Kontrol paneli oturum açmış oturumunuzu da kabul eder (Authorization: Bearer olarak gönderilen bir Cognito JWT), ancak betikler ve entegrasyonlar için doğru araç API anahtarıdır.

Aşağıdaki tüm örnekler anahtarı BADGES_API_KEY adlı bir ortam değişkeninden okur.

Adım 2: Bir düzenleyici oluşturun

Düzenleyici, rozetin arkasında duran kuruluştur. Her doğrulama sayfasında ve Open Badge v2.0 verisinin içinde görünür, bu yüzden insanların gerçekten tanıdığı adı kullanın.

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

Zorunlu alanlar name (en az 3 karakter), url (geçerli bir http veya https adresi) ve email alanlarıdır. İsteğe bağlı alanlar logo (base64 kodlu bir görsel) ve herkese açık kimlik bilgisi sayfalarınızda “LinkedIn Profiline Ekle” düğmesini açan linkedinOrganizationId alanıdır.

Yanıt, düzenleyici tanımlayıcısını içerir:

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

Bu değeri döndüğü haliyle aynen saklayın. Bir sonraki adımın girdisidir.

Düzenleyici doğrulaması

Rozetler yalnızca doğrulanmış bir düzenleyici altında oluşturulabilir. Doğrulama şöyle işler:

• Düzenleyici e-postası hesabınızdaki e-postayla eşleşirse düzenleyici otomatik olarak doğrulanır. İlk deneme için en hızlı yol budur.
• E-posta farklıysa, o adrese kod içeren bir doğrulama e-postası gider. Rozet oluşturmadan önce kodu kontrol panelinde (veya düzenleyiciler API’si üzerinden) onaylarsınız.

Bu yüzden bu öğretici için kaydolurken kullandığınız e-postayı kullanın.

Adım 3: Bir rozet oluşturun

Rozet, yeniden kullanılabilir şablondur: ad, açıklama, ölçütler ve görsel. Daha sonra verdiğiniz her ödül ona geri bağlanır.

İstek düz JSON’dur. Görsel base64 dizesi olarak gider, yani uğraşılacak bir multipart yükleme yoktur. data:image/png;base64, gibi bir data URL öneki kabul edilir ve kaldırılır.

JavaScript (Node 18 veya üzeri):

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)

Beş alanın tamamı (name, description, criteria, image, issuerId) zorunludur. Bilmeye değer iki isteğe bağlı alan var: alıcıların sosyal ağlarda paylaşırken gördüğü varsayılan metin olan shareText ({{badge_name}}, {{issuer_name}} ve {{award_url}} yer tutucularını destekler) ve rozetin daha sonra katman katman düzenlenebilmesi için görsel tasarımcı belgesini saklayan designJson.

Başarılı bir çağrı, { "badgeId": "<id>" } ile HTTP 200 döndürür. Görsel kalıcı olarak saklanır ve rozet artık herkesin getirebileceği bir Open Badge v2.0 BadgeClass’tır.

Rozetleri kodla oluşturmalı mısınız?

Genellikle hayır. Rozet tasarımı yaratıcı bir iştir ve görsel tasarımcı (80’den fazla şablon, şekil, simge, 11 yazı tipi ve özel yüklemeler) bunun için bir betikten çok daha iyi bir yerdir. Yaygın bir model, her rozeti kontrol panelinde bir kez tasarlamak ve entegrasyonunuzun yalnızca ona karşı ödül vermesidir. Rozetlerinizi GET /badges ile listeleyebilir ve istediğinizin id değerini kopyalayabilirsiniz.

Rozetleri programatik olarak ürettiğinizde, örneğin yüzlerce kurslu bir katalogda kurs başına bir tane, ya da bir test ortamını doldurduğunuzda API ile oluşturun.

Adım 4: Rozeti verin

Entegrasyonunuzun binlerce kez yapacağı çağrı budur. Rozeti, alıcıyı ve tarihi gönderin.

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

İnsanları en çok tökezleten kurallar:

• recipient, name ve email içeren iç içe bir nesnedir. recipientEmail gibi düz alanlar reddedilir.
• recipient.name en az 5 karakter olmalıdır.
• issuedOn zorunludur. Epoch milisaniye veya 2026-09-28 gibi bir ISO tarih dizesi gönderin.
• expires isteğe bağlıdır ve aynı biçimleri kabul eder.

Başarılı bir çağrı, gövdesinde awardId bulunan HTTP 200’dür. Alıcı e-postası Open Badge verisinde SHA-256 özeti olarak saklanır, yani herkese açık JSON onu asla ifşa etmez.

Adım 5: Doğrulama sayfasını ve Open Badge JSON’unu bulun

Ödül yanıtı size hazır bir bağlantı değil, bir tanımlayıcı verir. Tanımlayıcı bir GUID ile biter ve herkese açık sayfalar bu GUID’den oluşturulur:

• İnsan tarafından okunabilir doğrulama sayfası: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

awardId değeriniz tam bir URL olarak dönerse, son yol bölümünü GUID olarak kullanın.

İkisi de herkese açıktır. Bağlantıya sahip herkes hesap oluşturmadan kimlik bilgisini doğrulayabilir; amaç da budur: bir işveren veya kabul görevlisi bir rozeti on saniyede kontrol edebilmelidir.

Dünyanın ne gördüğünü görmek için JSON’u getirin:

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

Bir Open Badge v2.0 Assertion alırsınız: atıf yaptığı rozet, özetlenmiş alıcı kimliği, veriliş tarihi ve barındırılan assertion’a işaret eden bir doğrulama bloğu. Standart Open Badges verisi olduğundan, biçimi anlayan her araç onu okuyabilir. Open Badges’i tescilli bir PDF yerine seçmenin nedeni bu taşınabilirliktir; Open Badges ve PDF sertifikaları yazısı bu takası daha derinlemesine ele alır.

Alıcılar kimlik bilgisini nasıl alır

Ödül oluşturmak, alıcıya haber vermekten ayrı bir iştir. Alıcılar kimlik bilgilerini badges.ninja/me adresindeki alıcı portalından açabilir; portal parolasız sihirli bağlantıyla giriş kullanır. Ayrıca badges.ninja/u/<handle> adresinde herkese açık bir profil yayımlayabilirler. Doğrulama sayfasından rozeti LinkedIn’e ekleyebilir, PDF sertifikayı indirebilir veya bağlantıyı paylaşabilirler.

İlk testler için kendi e-posta adresinize bir ödül gönderin ve alıcı deneyimini baştan sona gezin. Rozet açıklamasının kulağa tuhaf gelmesi gibi şeyleri fark etmenin en hızlı yolu budur.

Can yakmayan hata yönetimi

API, sıradan HTTP durum kodlarını kullanır. Karşılaşacaklarınız şunlardır:

İki pratik ipucu. Birincisi, 400’ü bir veri sorunu olarak ele alın ve yanıt gövdesini günlüğe kaydedin; hatalı alanı o söyler. İkincisi, entegrasyonunuzu kendi tarafınızda idempotent yapın: awardId değerini kendi veritabanınızdaki tamamlanma kaydının yanında saklayın ve API’yi yeniden çağırmadan önce onu kontrol edin. Böylece yeniden denenen bir webhook veya yeniden çalışan bir iş aynı kişiye asla iki kimlik bilgisi vermez.

Gerçek bir entegrasyonda hepsini bir araya getirmek

Tipik bir kurgu şöyle görünür:

1. Rozetleri kontrol panelinde tasarlayın, kurs veya kilometre taşı başına bir tane, ve her rozet kimliğini not edin.
2. Sisteminizde kurstan rozet kimliğine bir eşleme saklayın.
3. Bir öğrenci kursu tamamladığında, sunucunuz adı, e-postası ve tamamlanma tarihiyle POST /awards çağrısı yapar.
4. Dönen awardId değerini tamamlanma kaydıyla birlikte kaydedin.
5. Doğrulama bağlantısını kendi ürününüzün içinde gösterin; öğrenci ayrılmadan görsün.

Kod yazmak istemiyorsanız, JSON gövdeli ve özel başlıklı bir HTTP isteği gönderebilen her otomasyon aracında aynı çağrı çalışır. Onu https://api.badges.ninja/awards adresine yönlendirin ve form veya elektronik tablo alanlarınızı badgeId, recipient.name, recipient.email ve issuedOn alanlarına eşleyin.

Bilmeye değer planlar ve sınırlar

API her planda kullanılabilir; kilidini açmak için ekstra ödeme yapmazsınız. Free plan ($0) 2 düzenleyici, 5 rozet, 2 koltuk, 1 API anahtarı ve yılda 1.200 kimlik bilgisini kapsar. Starter ayda $9, Pro ise ayda $29 olup daha yüksek sınırlar sunar. Bir devreye almayı boyutlandırmadan önce güncel rakamlar için fiyatlandırma sayfasına bakın. Diğer platformların API erişimi için ne kadar aldığını karşılaştırıyorsanız, Credly alternatifi yazısı maliyetleri yan yana koyar.

Sırada ne var

• Tam uç nokta başvurusu, 40 dilde sunulan API belgelerinde bulunur.
• Kimlik doğrulama ayrıntıları ve anahtar yönetimi için kimlik doğrulama kılavuzuna bakın.
• Hata kodlarını derinlemesine incelemek için hatalar başvurusuna bakın.
• Tek seferde tek çağrı size dar gelmeye başladığında, kontrol panelinde toplu ödülleri kullanın: bir CSV yükleyin, gerekirse çalıştırmayı duraklatın veya sürdürün.

Zor kısım ilk başarılı ödüldür. Sonrasında geriye, aynı çağrıyı başarıların zaten kaydedildiği yerlere bağlamak kalır.

İlk doğrulanabilir kimlik bilginizi vermeye hazır mısınız? badges.ninja’da ücretsiz başlayın — görsel tasarımcı, herkese açık doğrulama sayfası, PDF sertifika, Open Badge v2.0 çıktısı. Kredi kartı gerekmez.