Badges Ninja REST API দিয়ে Open Badge ইস্যু করুন: কুইকস্টার্ট

বেশিরভাগ ক্রেডেনশিয়াল প্রোগ্রামের কখনোই API লাগে না। আপনি যদি বছরে কয়েকশো গ্র্যাজুয়েটের একটি কোর্স চালান, ড্যাশবোর্ডই সব করে দেয়: ভিজ্যুয়াল ডিজাইনারে একটি ব্যাজ ডিজাইন করুন, একটি CSV আপলোড করুন, আর প্রত্যেক প্রাপক পান একটি যাচাই পেজ ও একটি PDF সার্টিফিকেট। আপনার পরিস্থিতি এমন হলে CSV থেকে Open Badge ইস্যু করার পদ্ধতি দিয়ে শুরু করুন, পরে এখানে ফিরে আসুন।

ক্রেডেনশিয়াল যখন অন্য কোনো সিস্টেমকে ইস্যু করতে হয়, তখনই API-র আসল মূল্য: আপনার লার্নিং প্ল্যাটফর্ম একটি কোর্স সম্পন্ন চিহ্নিত করে, আপনার রেজিস্ট্রেশন টুল একটি ইভেন্ট বন্ধ করে, আপনার HR সিস্টেম একটি কমপ্লায়েন্স মডিউল শেষ হওয়ার তথ্য রাখে। এসব ক্ষেত্রে প্রতি সপ্তাহের শেষে কেউ স্প্রেডশিট এক্সপোর্ট করতে চায় না। সম্পন্ন হওয়ার মুহূর্তে একটিমাত্র HTTP কল অনেক সহজ, আর অর্জনের স্মৃতি তাজা থাকতেই প্রাপক তাঁর ব্যাজ পান।

এই কুইকস্টার্ট পুরো পথটি চারটি কলে দেখায়: একটি কী নিন, একটি ইস্যুকারী তৈরি করুন, একটি ব্যাজ তৈরি করুন, সেটি প্রদান করুন। তারপর দেখব প্রাপকের হাতে যাচাই লিংক কীভাবে পৌঁছে দেবেন এবং ফলাফল কীভাবে যাচাই করবেন। নিচের প্রতিটি রিকোয়েস্টের গঠন ডিপ্লয় করা হ্যান্ডলার থেকে নেওয়া, তাই কপি করে সরাসরি চালাতে পারেন।

শুরু করার আগে যা লাগবে

• badges.ninja-এ একটি বিনামূল্যের অ্যাকাউন্ট। এই টিউটোরিয়ালের জন্য Free প্ল্যানই যথেষ্ট: এতে আছে ২টি ইস্যুকারী, ৫টি ব্যাজ, ২টি সিট ও ১টি API কী।
• ড্যাশবোর্ড থেকে তৈরি একটি API কী।
• ব্যাজের ছবির জন্য একটি PNG বা JPG, অথবা ভিজ্যুয়াল ডিজাইনারে ডিজাইন করা একটি ব্যাজ।

সবকিছুর বেস URL হলো https://api.badges.ninja।

ধাপ ১: একটি API কী তৈরি করুন

সাইন ইন করুন, সাইডবারে API Keys খুলুন এবং Create API Key-এ ক্লিক করুন। কীটি কোথায় ব্যবহার হবে তা বোঝায় এমন একটি নাম দিন, যেমন “LMS ইন্টিগ্রেশন”, যাতে পরে রোটেট করার সময় কীগুলো আলাদা করতে পারেন।

কীটি ঠিক একবারই দেখানো হয়। সঙ্গে সঙ্গে এটি আপনার সিক্রেট ম্যানেজারে বা একটি এনভায়রনমেন্ট ভ্যারিয়েবলে কপি করে রাখুন। কী দেখতে bws_-এর পরে ৩২টি হেক্স অক্ষর, এবং প্রতিটি রিকোয়েস্টে এটি X-Api-Key হেডারে পাঠাতে হয়। একই স্ক্রিন থেকে কী বাতিল করলে তা সঙ্গে সঙ্গে কার্যকর হয়।

পরে ঝামেলা এড়াতে কিছু অভ্যাস:

• কী কখনো ফ্রন্ট-এন্ড কোডে বা পাবলিক রিপোজিটরিতে রাখবেন না। API কল করুন সার্ভার, সার্ভারলেস ফাংশন বা অটোমেশন টুল থেকে।
• প্রতি ইন্টিগ্রেশনের জন্য একটি কী ব্যবহার করুন। একটি ফাঁস হলে সব নয়, একটি ইন্টিগ্রেশনই বাতিল করতে হবে।
• ড্যাশবোর্ড আপনার সাইন-ইন সেশনও (Authorization: Bearer হিসেবে পাঠানো Cognito JWT) গ্রহণ করে, কিন্তু স্ক্রিপ্ট ও ইন্টিগ্রেশনের জন্য API কী-ই সঠিক হাতিয়ার।

নিচের সব উদাহরণ কীটি BADGES_API_KEY নামের এনভায়রনমেন্ট ভ্যারিয়েবল থেকে পড়ে।

ধাপ ২: একটি ইস্যুকারী তৈরি করুন

ইস্যুকারী হলো সেই প্রতিষ্ঠান যা ব্যাজের পেছনে দাঁড়িয়ে আছে। এটি প্রতিটি যাচাই পেজে এবং Open Badge v2.0 ডেটার ভেতরে দেখা যায়, তাই মানুষ যে নামে আপনাদের চেনে সেটিই ব্যবহার করুন।

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

আবশ্যিক ফিল্ড হলো name (কমপক্ষে ৩ অক্ষর), url (একটি বৈধ http বা https ঠিকানা) এবং email। ঐচ্ছিক ফিল্ড হলো logo (base64-এনকোডেড ছবি) ও linkedinOrganizationId, যা আপনার পাবলিক ক্রেডেনশিয়াল পেজে Add to LinkedIn Profile বাটন চালু করে।

রেসপন্সে ইস্যুকারীর আইডেন্টিফায়ার থাকে:

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

ওই মানটি ঠিক যেভাবে ফেরত এসেছে সেভাবেই রাখুন। এটিই পরের ধাপের ইনপুট।

ইস্যুকারী যাচাই

ব্যাজ শুধু যাচাইকৃত ইস্যুকারীর অধীনে তৈরি করা যায়। যাচাই এভাবে কাজ করে:

• ইস্যুকারীর ইমেল আপনার অ্যাকাউন্টের ইমেলের সঙ্গে মিললে ইস্যুকারী স্বয়ংক্রিয়ভাবে যাচাই হয়ে যায়। প্রথম পরীক্ষার জন্য এটাই দ্রুততম পথ।
• ইমেল ভিন্ন হলে ওই ঠিকানায় একটি কোডসহ যাচাই ইমেল যায়। ব্যাজ তৈরির আগে ড্যাশবোর্ডে (বা ইস্যুকারী API-র মাধ্যমে) কোডটি নিশ্চিত করতে হবে।

তাই এই টিউটোরিয়ালে সাইন আপের সময় ব্যবহার করা ইমেলটিই ব্যবহার করুন।

ধাপ ৩: একটি ব্যাজ তৈরি করুন

ব্যাজ হলো পুনর্ব্যবহারযোগ্য টেমপ্লেট: নাম, বিবরণ, মানদণ্ড ও ছবি। পরে আপনি যত প্রদান ইস্যু করবেন, প্রতিটি এর দিকেই নির্দেশ করবে।

রিকোয়েস্ট সাধারণ JSON। ছবি base64 স্ট্রিং হিসেবে যায়, তাই মাল্টিপার্ট আপলোডের ঝামেলা নেই। data:image/png;base64,-এর মতো data URL প্রিফিক্স গ্রহণ করা হয় এবং বাদ দেওয়া হয়।

JavaScript (Node 18 বা পরবর্তী):

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)

পাঁচটি ফিল্ডই (name, description, criteria, image, issuerId) আবশ্যিক। দুটি ঐচ্ছিক ফিল্ড জানা থাকা ভালো: shareText, যা সোশ্যাল নেটওয়ার্কে শেয়ার করার সময় প্রাপকেরা ডিফল্ট টেক্সট হিসেবে দেখেন (এটি {{badge_name}}, {{issuer_name}} ও {{award_url}} প্লেসহোল্ডার সমর্থন করে), এবং designJson, যা ভিজ্যুয়াল ডিজাইনারের একটি ডকুমেন্ট সংরক্ষণ করে যাতে পরে ব্যাজটি লেয়ার ধরে ধরে এডিট করা যায়।

সফল হলে HTTP 200 সহ { "badgeId": "<id>" } ফেরত আসে। ছবিটি স্থায়ীভাবে সংরক্ষিত হয়, এবং ব্যাজটি এখন একটি Open Badge v2.0 BadgeClass যা যে কেউ আনতে পারে।

আদৌ কি কোডে ব্যাজ তৈরি করা উচিত?

সাধারণত না। ব্যাজ ডিজাইন একটি সৃজনশীল কাজ, আর ভিজ্যুয়াল ডিজাইনার (৮০+ টেমপ্লেট, আকৃতি, আইকন, ১১টি ফন্ট ও কাস্টম আপলোড) স্ক্রিপ্টের চেয়ে অনেক ভালো জায়গা। প্রচলিত ধরন হলো ড্যাশবোর্ডে প্রতিটি ব্যাজ একবার ডিজাইন করা, তারপর আপনার ইন্টিগ্রেশন শুধু সেটির বিপরীতে প্রদান ইস্যু করবে। GET /badges দিয়ে আপনার ব্যাজের তালিকা পেয়ে প্রয়োজনীয়টির id কপি করতে পারেন।

API দিয়ে ব্যাজ তৈরি করুন যখন সেগুলো প্রোগ্রাম করে তৈরি করছেন, যেমন শতশত কোর্সের ক্যাটালগে প্রতি কোর্সে একটি, অথবা যখন টেস্ট এনভায়রনমেন্টে ডেটা বসাচ্ছেন।

ধাপ ৪: ব্যাজ প্রদান করুন

এই কলটিই আপনার ইন্টিগ্রেশন হাজার হাজার বার করবে। ব্যাজ, প্রাপক ও তারিখ পাঠান।

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

যে নিয়মগুলোতে মানুষ আটকে যায়:

• recipient হলো name ও email সহ একটি নেস্টেড অবজেক্ট। recipientEmail-এর মতো ফ্ল্যাট ফিল্ড প্রত্যাখ্যাত হয়।
• recipient.name কমপক্ষে ৫ অক্ষরের হতে হবে।
• issuedOn আবশ্যিক। epoch মিলিসেকেন্ড অথবা 2026-09-28-এর মতো ISO তারিখ স্ট্রিং পাঠান।
• expires ঐচ্ছিক এবং একই ফরম্যাট নেয়।

সফল হলে HTTP 200 আসে, বডিতে থাকে awardId। প্রাপকের ইমেল Open Badge ডেটায় SHA-256 হ্যাশ হিসেবে সংরক্ষিত হয়, তাই পাবলিক JSON কখনো তা প্রকাশ করে না।

ধাপ ৫: যাচাই পেজ ও Open Badge JSON খুঁজে নিন

প্রদানের রেসপন্স আপনাকে একটি আইডেন্টিফায়ার দেয়, তৈরি লিংক নয়। আইডেন্টিফায়ারটি একটি GUID দিয়ে শেষ হয়, এবং পাবলিক পেজগুলো ওই GUID থেকেই তৈরি:

• মানুষের পড়ার উপযোগী যাচাই পেজ: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

আপনার awardId পুরো URL হিসেবে এলে পাথের শেষ অংশটিকে GUID হিসেবে ব্যবহার করুন।

দুটিই পাবলিক। লিংক থাকলে যে কেউ অ্যাকাউন্ট ছাড়াই ক্রেডেনশিয়াল যাচাই করতে পারেন, আর এটাই আসল কথা: একজন নিয়োগকর্তা বা ভর্তি কর্মকর্তা দশ সেকেন্ডে একটি ব্যাজ যাচাই করতে পারবেন।

বিশ্ব কী দেখে তা দেখতে JSON আনুন:

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

আপনি একটি Open Badge v2.0 Assertion পাবেন: যে ব্যাজের উল্লেখ আছে, হ্যাশ করা প্রাপক পরিচয়, ইস্যুর তারিখ, এবং হোস্ট করা অ্যাসারশনের দিকে ফিরে নির্দেশ করা একটি যাচাই ব্লক। এটি স্ট্যান্ডার্ড Open Badges ডেটা বলে ফরম্যাট বোঝে এমন যেকোনো টুল এটি পড়তে পারে। এই পোর্টেবিলিটিই মালিকানাধীন PDF-এর বদলে Open Badges বেছে নেওয়ার কারণ; Open Badges বনাম PDF সার্টিফিকেট লেখায় এই সমঝোতা নিয়ে আরও গভীর আলোচনা আছে।

প্রাপকেরা কীভাবে ক্রেডেনশিয়াল পান

প্রদান তৈরি করা আর প্রাপককে জানানো আলাদা বিষয়। প্রাপকেরা badges.ninja/me-তে প্রাপক পোর্টালের মাধ্যমে তাঁদের ক্রেডেনশিয়াল খুলতে পারেন, যেখানে পাসওয়ার্ডহীন ম্যাজিক-লিংক সাইন-ইন চলে, এবং badges.ninja/u/<handle>-এ একটি পাবলিক প্রোফাইল প্রকাশ করতে পারেন। যাচাই পেজ থেকে তাঁরা ব্যাজটি LinkedIn-এ যোগ করতে, PDF সার্টিফিকেট ডাউনলোড করতে বা লিংক শেয়ার করতে পারেন।

প্রথম কয়েকটি পরীক্ষায় নিজের ইমেল ঠিকানায় নিজেকে একটি প্রদান পাঠান এবং প্রাপকের অভিজ্ঞতাটি ঘুরে দেখুন। ব্যাজের বিবরণ অস্বস্তিকরভাবে পড়তে লাগছে কি না, এমন বিষয় ধরার এটাই দ্রুততম উপায়।

ঝামেলাহীন ত্রুটি পরিচালনা

API সাধারণ HTTP স্ট্যাটাস কোড ব্যবহার করে। যেগুলোর মুখোমুখি হবেন:

দুটি ব্যবহারিক পরামর্শ। প্রথমত, 400-কে ডেটার সমস্যা হিসেবে দেখুন এবং রেসপন্স বডি লগ করুন, কারণ সেখানে ব্যর্থ ফিল্ডের নাম থাকে। দ্বিতীয়ত, নিজের দিকে ইন্টিগ্রেশনকে আইডেম্পোটেন্ট করুন: আপনার ডেটাবেসে সম্পন্ন হওয়ার রেকর্ডের পাশে awardId সংরক্ষণ করুন, এবং আবার API কল করার আগে সেটি দেখে নিন। তাহলে পুনরায় চেষ্টা করা ওয়েবহুক বা আবার চালানো জব একই ব্যক্তিকে কখনো দুটি ক্রেডেনশিয়াল ইস্যু করবে না।

বাস্তব ইন্টিগ্রেশনে সবকিছু একসঙ্গে

একটি সাধারণ সংযোজন দেখতে এমন:

1. ড্যাশবোর্ডে ব্যাজ ডিজাইন করুন, প্রতি কোর্স বা মাইলফলকে একটি, এবং প্রতিটি ব্যাজের ID টুকে রাখুন।
2. আপনার সিস্টেমে কোর্স থেকে ব্যাজ ID-র একটি ম্যাপিং রাখুন।
3. শিক্ষার্থী কোর্স শেষ করলে আপনার সার্ভার তাঁর নাম, ইমেল ও সম্পন্ন হওয়ার তারিখ দিয়ে POST /awards কল করে।
4. ফেরত আসা awardId সম্পন্ন হওয়ার রেকর্ডের বিপরীতে সংরক্ষণ করুন।
5. যাচাই লিংকটি আপনার নিজের প্রোডাক্টের ভেতরে দেখান, যাতে শিক্ষার্থী বাইরে না গিয়েই তা দেখতে পান।

কোড লিখতে না চাইলে JSON বডি ও কাস্টম হেডারসহ HTTP রিকোয়েস্ট পাঠাতে পারে এমন যেকোনো অটোমেশন টুল থেকে একই কল কাজ করে। এটিকে https://api.badges.ninja/awards-এ নির্দেশ করুন এবং আপনার ফর্ম বা স্প্রেডশিটের ফিল্ডগুলোকে badgeId, recipient.name, recipient.email ও issuedOn-এর সঙ্গে ম্যাপ করুন।

প্ল্যান ও সীমা, যা জানা দরকার

API প্রতিটি প্ল্যানেই পাওয়া যায়; এটি আনলক করতে অতিরিক্ত দিতে হয় না। Free প্ল্যান ($0) এ আছে ২টি ইস্যুকারী, ৫টি ব্যাজ, ২টি সিট, ১টি API কী এবং বছরে ১,২০০টি ক্রেডেনশিয়াল। Starter মাসে $9 এবং Pro মাসে $29, উচ্চতর সীমাসহ। রোলআউটের আকার ঠিক করার আগে বর্তমান সংখ্যার জন্য মূল্য পেজ দেখে নিন। অন্য প্ল্যাটফর্ম API অ্যাক্সেসের জন্য কত নেয় তা তুলনা করতে চাইলে Credly alternative খরচগুলো পাশাপাশি সাজিয়েছে।

এরপর কোথায় যাবেন

• সম্পূর্ণ এন্ডপয়েন্ট রেফারেন্স আছে API ডকুমেন্টেশনে, যা ৪০টি ভাষায় পাওয়া যায়।
• অথেনটিকেশনের বিস্তারিত ও কী ব্যবস্থাপনার জন্য দেখুন অথেনটিকেশন গাইড।
• ত্রুটি কোডের গভীর বিবরণের জন্য দেখুন ত্রুটি রেফারেন্স।
• একবারে একটি কল যখন আর যথেষ্ট নয়, ড্যাশবোর্ডে বাল্ক প্রদান ব্যবহার করুন: একটি CSV আপলোড করুন, এবং দরকার হলে রান বিরতি দিন বা আবার চালু করুন।

প্রথম সফল প্রদানই কঠিন অংশ। এরপর বাকি কাজ হলো একই কলটি সেসব জায়গায় জুড়ে দেওয়া যেখানে অর্জন আগে থেকেই নথিভুক্ত হয়।

আপনার প্রথম যাচাইযোগ্য ক্রেডেনশিয়াল ইস্যু করতে প্রস্তুত? badges.ninja-তে বিনামূল্যে শুরু করুন — ভিজ্যুয়াল ডিজাইনার, পাবলিক যাচাই পেজ, PDF সার্টিফিকেট, Open Badge v2.0 আউটপুট। ক্রেডিট কার্ড লাগবে না।