Badges Ninja REST API से Open Badges जारी करें: क्विकस्टार्ट

ज़्यादातर क्रेडेंशियल प्रोग्राम को API की ज़रूरत ही नहीं पड़ती। अगर आप साल में कुछ सौ स्नातकों वाला कोर्स चलाते हैं, तो डैशबोर्ड ही सब कर देता है: आप विज़ुअल डिज़ाइनर में बैज डिज़ाइन करते हैं, CSV अपलोड करते हैं, और हर प्राप्तकर्ता को एक सत्यापन पेज और PDF सर्टिफ़िकेट मिल जाता है। अगर आपकी स्थिति यही है, तो CSV से Open Badges कैसे जारी करें से शुरू करें और बाद में यहाँ लौट आएँ।

API तब काम आती है जब क्रेडेंशियल किसी दूसरे सिस्टम से जारी होने चाहिए: आपका लर्निंग प्लेटफ़ॉर्म कोर्स पूरा होने पर उसे चिह्नित करता है, आपका रजिस्ट्रेशन टूल इवेंट बंद करता है, आपका HR सिस्टम पूरा हुआ कंप्लायंस मॉड्यूल दर्ज करता है। ऐसे मामलों में कोई भी हर हफ़्ते के अंत में स्प्रेडशीट एक्सपोर्ट नहीं करना चाहता। पूरा होते ही एक HTTP कॉल कहीं आसान है, और प्राप्तकर्ता को बैज तब मिलता है जब उपलब्धि ताज़ा होती है।

यह क्विकस्टार्ट पूरा रास्ता चार कॉल में दिखाता है: कुंजी लें, जारीकर्ता बनाएँ, बैज बनाएँ, उसे प्रदान करें। फिर हम देखेंगे कि सत्यापन लिंक प्राप्तकर्ता तक कैसे पहुँचाएँ और नतीजा कैसे जाँचें। नीचे दिया हर रिक्वेस्ट शेप डिप्लॉय किए गए हैंडलर से लिया गया है, इसलिए आप इसे पेस्ट करके सीधे चला सकते हैं।

शुरू करने से पहले आपको क्या चाहिए

• badges.ninja पर एक मुफ़्त अकाउंट। इस ट्यूटोरियल के लिए Free प्लान काफ़ी है: इसमें 2 जारीकर्ता, 5 बैज, 2 सीट और 1 API कुंजी शामिल हैं।
• डैशबोर्ड से बनाई गई एक API कुंजी।
• बैज की इमेज के लिए एक PNG या JPG, या विज़ुअल डिज़ाइनर में बनाया गया कोई बैज।

हर चीज़ का बेस URL https://api.badges.ninja है।

चरण 1: API कुंजी बनाएँ

साइन इन करें, साइडबार में API Keys खोलें, और Create API Key पर क्लिक करें। उसे ऐसा नाम दें जो बताए कि वह कहाँ इस्तेमाल होगी, जैसे “LMS integration”, ताकि बाद में कुंजियाँ बदलते समय आप उन्हें अलग पहचान सकें।

कुंजी सिर्फ़ एक बार दिखाई जाती है। उसे तुरंत अपने सीक्रेट मैनेजर या किसी एनवायरनमेंट वेरिएबल में कॉपी कर लें। कुंजियाँ bws_ से शुरू होकर 32 हेक्स अक्षरों की होती हैं, और आप उन्हें हर रिक्वेस्ट में X-Api-Key हेडर में भेजते हैं। उसी स्क्रीन से कुंजी रद्द करने पर वह तुरंत प्रभावी हो जाती है।

कुछ आदतें जो आगे परेशानी से बचाती हैं:

• कुंजी को कभी फ़्रंट-एंड कोड या सार्वजनिक रिपॉज़िटरी में न रखें। API को सर्वर, सर्वरलेस फ़ंक्शन या ऑटोमेशन टूल से कॉल करें।
• हर इंटीग्रेशन के लिए एक अलग कुंजी रखें। अगर एक लीक हो जाए, तो आप सभी की जगह सिर्फ़ एक इंटीग्रेशन रद्द करेंगे।
• डैशबोर्ड आपका साइन-इन सेशन (Authorization: Bearer के रूप में भेजा गया Cognito JWT) भी स्वीकार करता है, लेकिन स्क्रिप्ट और इंटीग्रेशन के लिए API कुंजी ही सही साधन है।

नीचे के सभी उदाहरण कुंजी को BADGES_API_KEY नाम के एनवायरनमेंट वेरिएबल से पढ़ते हैं।

चरण 2: जारीकर्ता बनाएँ

जारीकर्ता वह संगठन है जो बैज के पीछे खड़ा होता है। वह हर सत्यापन पेज पर और 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 (कम से कम 3 अक्षर), url (एक मान्य http या https पता) और email। वैकल्पिक फ़ील्ड हैं logo (base64-एन्कोडेड इमेज) और linkedinOrganizationId, जो आपके सार्वजनिक क्रेडेंशियल पेजों पर Add to LinkedIn Profile बटन चालू करता है।

रिस्पॉन्स में जारीकर्ता का आइडेंटिफ़ायर होता है:

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

उस मान को ठीक वैसा ही रखें जैसा लौटाया गया है। अगला चरण इसी को इनपुट के रूप में लेता है।

जारीकर्ता का सत्यापन

बैज सिर्फ़ सत्यापित जारीकर्ता के तहत बनाए जा सकते हैं। सत्यापन इस तरह होता है:

• अगर जारीकर्ता का ईमेल आपके अकाउंट के ईमेल से मेल खाता है, तो जारीकर्ता अपने-आप सत्यापित हो जाता है। पहले टेस्ट के लिए यह सबसे तेज़ रास्ता है।
• अगर ईमेल अलग है, तो उस पते पर कोड वाला एक सत्यापन ईमेल जाता है। बैज बनाने से पहले आप डैशबोर्ड में (या issuers API से) उस कोड की पुष्टि करते हैं।

इसलिए इस ट्यूटोरियल के लिए वही ईमेल इस्तेमाल करें जिससे आपने साइन अप किया था।

चरण 3: बैज बनाएँ

बैज दोबारा इस्तेमाल होने वाला टेम्पलेट है: नाम, विवरण, मानदंड और इमेज। बाद में आप जो भी अवॉर्ड जारी करेंगे, वह इसी की ओर इशारा करेगा।

रिक्वेस्ट सादा 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 है जिसे कोई भी प्राप्त कर सकता है।

क्या बैज कोड से बनाने चाहिए?

आम तौर पर नहीं। बैज डिज़ाइन एक रचनात्मक काम है, और विज़ुअल डिज़ाइनर (80+ टेम्पलेट, आकार, आइकन, 11 फ़ॉन्ट और कस्टम अपलोड) इसके लिए स्क्रिप्ट से कहीं बेहतर जगह है। एक आम तरीका यह है कि हर बैज को डैशबोर्ड में एक बार डिज़ाइन करें, फिर आपका इंटीग्रेशन सिर्फ़ उसी के विरुद्ध अवॉर्ड जारी करे। आप GET /badges से अपने बैज की सूची देख सकते हैं और जो चाहिए उसका id कॉपी कर सकते हैं।

बैज API से तब बनाएँ जब आप उन्हें प्रोग्रामैटिक रूप से जनरेट करते हों, जैसे सैकड़ों कोर्स वाले कैटलॉग में हर कोर्स के लिए एक, या जब आप टेस्ट एनवायरनमेंट तैयार कर रहे हों।

चरण 4: बैज प्रदान करें

यह वह कॉल है जो आपका इंटीग्रेशन हज़ारों बार करेगा। बैज, प्राप्तकर्ता और तारीख भेजें।

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 कम से कम 5 अक्षरों का होना चाहिए।
• issuedOn ज़रूरी है। epoch मिलीसेकंड या 2026-09-28 जैसी ISO तारीख की स्ट्रिंग भेजें।
• expires वैकल्पिक है और वही फ़ॉर्मेट लेता है।

सफलता पर HTTP 200 मिलता है, जिसकी बॉडी में awardId होता है। प्राप्तकर्ता का ईमेल Open Badge डेटा में SHA-256 हैश के रूप में सहेजा जाता है, इसलिए सार्वजनिक JSON उसे कभी उजागर नहीं करता।

चरण 5: सत्यापन पेज और 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 मिलता है: जिस बैज का वह हवाला देता है, हैश की गई प्राप्तकर्ता पहचान, जारी करने की तारीख, और होस्ट किए गए assertion की ओर इशारा करने वाला एक verification ब्लॉक। चूँकि यह मानक Open Badges डेटा है, इस फ़ॉर्मेट को समझने वाला कोई भी टूल इसे पढ़ सकता है। किसी मालिकाना PDF की जगह Open Badges चुनने की वजह यही पोर्टेबिलिटी है; Open Badges बनाम PDF सर्टिफ़िकेट इस समझौते पर और गहराई से बात करता है।

प्राप्तकर्ताओं को क्रेडेंशियल कैसे मिलता है

अवॉर्ड बनाना और प्राप्तकर्ता को बताना दो अलग बातें हैं। प्राप्तकर्ता अपने क्रेडेंशियल badges.ninja/me के रिसीपिएंट पोर्टल से खोल सकते हैं, जो बिना पासवर्ड के मैजिक-लिंक साइन-इन इस्तेमाल करता है, और वे badges.ninja/u/<handle> पर एक सार्वजनिक प्रोफ़ाइल प्रकाशित कर सकते हैं। सत्यापन पेज से वे बैज को LinkedIn में जोड़ सकते हैं, PDF सर्टिफ़िकेट डाउनलोड कर सकते हैं, या लिंक शेयर कर सकते हैं।

पहले कुछ टेस्ट के लिए, अपने ही ईमेल पते पर एक अवॉर्ड भेजें और प्राप्तकर्ता का अनुभव खुद देखें। बैज के विवरण के अटपटे लगने जैसी बातें पकड़ने का यह सबसे तेज़ तरीका है।

एरर हैंडलिंग जो परेशान न करे

API सामान्य HTTP स्टेटस कोड इस्तेमाल करती है। जो आपको मिलेंगे:

दो व्यावहारिक सुझाव। पहला, 400 को डेटा की समस्या मानें और रिस्पॉन्स बॉडी लॉग करें, क्योंकि उसमें विफल फ़ील्ड का नाम होता है। दूसरा, अपनी तरफ़ से इंटीग्रेशन को idempotent बनाएँ: awardId को अपने डेटाबेस में पूर्णता रिकॉर्ड के साथ सहेजें, और API को दोबारा कॉल करने से पहले उसे जाँचें। इस तरह दोबारा भेजा गया webhook या फिर से चला जॉब किसी को कभी दो क्रेडेंशियल जारी नहीं करेगा।

असली इंटीग्रेशन में सब कुछ जोड़ना

एक सामान्य वायरिंग कुछ ऐसी दिखती है:

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) में 2 जारीकर्ता, 5 बैज, 2 सीट, 1 API कुंजी और प्रति वर्ष 1,200 क्रेडेंशियल शामिल हैं। Starter $9 प्रति माह है और Pro $29 प्रति माह, जिनमें ऊँची सीमाएँ हैं। रोलआउट का आकार तय करने से पहले मौजूदा आँकड़ों के लिए प्राइसिंग पेज देखें। अगर आप तुलना कर रहे हैं कि दूसरे प्लेटफ़ॉर्म API एक्सेस के लिए कितना लेते हैं, तो Credly alternative लागत को आमने-सामने रखता है।

आगे कहाँ जाएँ

• पूरा एंडपॉइंट रेफ़रेंस API दस्तावेज़ीकरण में है, जो 40 भाषाओं में उपलब्ध है।
• ऑथेंटिकेशन के ब्योरे और कुंजी संभालने के लिए ऑथेंटिकेशन गाइड देखें।
• एरर कोड गहराई से जानने के लिए एरर रेफ़रेंस देखें।
• जब एक-एक कॉल आपके लिए कम पड़ने लगे, तो डैशबोर्ड में बल्क अवॉर्ड इस्तेमाल करें: CSV अपलोड करें, और ज़रूरत हो तो रन को रोकें या फिर शुरू करें।

पहला सफल अवॉर्ड ही सबसे मुश्किल हिस्सा है। उसके बाद बस उसी कॉल को उन जगहों पर जोड़ना रह जाता है जहाँ उपलब्धियाँ पहले से दर्ज होती हैं।

अपना पहला सत्यापन योग्य क्रेडेंशियल जारी करने के लिए तैयार हैं? badges.ninja पर मुफ़्त शुरू करें — विज़ुअल डिज़ाइनर, सार्वजनिक सत्यापन पेज, PDF सर्टिफ़िकेट, Open Badge v2.0 आउटपुट। क्रेडिट कार्ड की ज़रूरत नहीं।