Awards API

बैज अवॉर्ड (असर्शन) बनाएँ और प्रबंधित करें — विशिष्ट प्राप्तकर्ताओं को जारी किए गए बैज।

सभी एंडपॉइंट के लिए X-Api-Key हेडर के माध्यम से प्रमाणीकरण आवश्यक है। देखें प्रमाणीकरण।

अवॉर्ड बनाना

एक प्राप्तकर्ता को बैज जारी करें।

POST /awards

पैरामीटर

पैरामीटर	प्रकार	अनिवार्य	विवरण
badgeId	string	हाँ	प्रदान करने वाला बैज ID
recipient	object	हाँ	प्राप्तकर्ता विवरण (नीचे देखें)
recipient.name	string	हाँ	प्राप्तकर्ता का पूरा नाम (न्यूनतम 5 अक्षर)
recipient.email	string	हाँ	प्राप्तकर्ता का ईमेल पता
issuedOn	string	हाँ	ISO 8601 प्रारूप में जारी तिथि (जैसे 2025-01-15)
expires	string	नहीं	ISO 8601 प्रारूप में समाप्ति तिथि
blockchain	string	नहीं	ऑन-चेन सत्यापन के लिए ब्लॉकचेन। केवल matchain समर्थित है। Pro प्लान पर उपलब्ध।

उदाहरण

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

प्रतिक्रिया

{
  "statusCode": 200,
  "info": {
    "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
  }
}

टिप्पणियाँ

• आपके मासिक कोटे के विरुद्ध एक अवॉर्ड के रूप में गिना जाता है (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo)। कोटा प्रत्येक बिलिंग अवधि में रीसेट होता है।
• blockchain पैरामीटर केवल Pro प्लान पर उपलब्ध है।

---

अवॉर्ड सूची

वैकल्पिक फ़िल्टरिंग और पेजिनेशन के साथ अवॉर्ड प्राप्त करें।

GET /awards

क्वेरी पैरामीटर

पैरामीटर	प्रकार	अनिवार्य	विवरण
filter	JSON string	नहीं	फ़िल्टर ऑब्जेक्ट (नीचे देखें)
lastEvaluatedKey	string	नहीं	पिछली प्रतिक्रिया से पेजिनेशन टोकन

फ़िल्टर ऑब्जेक्ट

filter पैरामीटर इन फ़ील्ड के साथ एक JSON स्ट्रिंग स्वीकार करता है:

फ़ील्ड	प्रकार	विवरण
badgeId	string	बैज ID द्वारा फ़िल्टर करें।
search	string	प्राप्तकर्ता के नाम या ईमेल में देखने के लिए सबस्ट्रिंग (देखें searchField)।
searchField	string	या तो name (डिफ़ॉल्ट) या email — खोज के लिए कॉलम।

lastEvaluatedKey के माध्यम से पेजिनेशन फ़िल्टर के साथ या बिना काम करता है। पृष्ठ आकार 50 है।

उदाहरण — सभी अवॉर्ड सूची

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

उदाहरण — बैज द्वारा फ़िल्टर

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

प्रतिक्रिया

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "recipient": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        },
        "issuedOn": "2025-01-15T00:00:00.000Z",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ],
    "lastEvaluatedKey": "eyJ..."
  }
}

यदि lastEvaluatedKey प्रतिक्रिया में मौजूद है, तो अधिक परिणाम हैं। अगले पृष्ठ को प्राप्त करने के लिए इसे अगले अनुरोध में क्वेरी पैरामीटर के रूप में पास करें।

---

अवॉर्ड ईमेल भेजें

प्राप्तकर्ता को उनके अवॉर्ड के बारे में एक ईमेल अधिसूचना भेजें।

POST /awards/{awardId}/send

पैरामीटर

पैरामीटर	प्रकार	अनिवार्य	विवरण
awardId	string	हाँ	अवॉर्ड ID (पथ पैरामीटर और बॉडी)
email	string	हाँ	प्राप्तकर्ता का ईमेल पता

उदाहरण

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

प्रतिक्रिया

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

अवॉर्ड साझा करें

ईमेल के माध्यम से कई प्राप्तकर्ताओं के साथ एक अवॉर्ड साझा करें।

POST /awards/{awardId}/share

पैरामीटर

पैरामीटर	प्रकार	अनिवार्य	विवरण
awardId	string	हाँ	अवॉर्ड ID (पथ पैरामीटर और बॉडी)
recipients	string	हाँ	ईमेल पतों की कॉमा-पृथक सूची
subject	string	हाँ	ईमेल विषय पंक्ति
message	string	हाँ	ईमेल संदेश बॉडी

उदाहरण

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

प्रतिक्रिया

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

PDF प्रमाणपत्र डाउनलोड करें

एक अवॉर्ड के लिए प्रिंट-तैयार A4 PDF प्रमाणपत्र जेनरेट करें।

GET /awards/{awardGuid}/pdf

कोई प्रमाणीकरण आवश्यक नहीं — यह एंडपॉइंट सार्वजनिक है ताकि प्राप्तकर्ता अपना प्रमाणपत्र डाउनलोड कर सकें।

उदाहरण

curl -OJ https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

प्रतिक्रिया Content-Type: application/pdf हेडर के साथ बाइनरी PDF है।

---

अवॉर्ड इवेंट ट्रैक करें

एक एंगेजमेंट इवेंट रिकॉर्ड करें (view, share, download, LinkedIn ऐड)। सार्वजनिक अवॉर्ड पृष्ठ द्वारा एंगेजमेंट आँकड़े भरने के लिए उपयोग किया जाता है। कोई प्रमाणीकरण आवश्यक नहीं।

POST /awards/{awardGuid}/event

पैरामीटर

पैरामीटर	प्रकार	अनिवार्य	विवरण
kind	string	हाँ	इनमें से एक view, share, download, linkedin_add।
network	string	नहीं	जब kind=share, सोशल नेटवर्क: linkedin, twitter, facebook, whatsapp, telegram, email, copy।

प्रति-IP डुप्लिकेट दमन: एक ही IP से एक ही kind को प्रति 24 घंटे में एक बार गिना जाता है।

उदाहरण

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"kind": "share", "network": "linkedin"}}'

---

अवॉर्ड आँकड़े प्राप्त करें

एक अवॉर्ड के लिए संचयी एंगेजमेंट काउंटर प्राप्त करें।

GET /awards/{awardGuid}/stats

कोई प्रमाणीकरण आवश्यक नहीं।

प्रतिक्रिया

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}