API รางวัล

สร้างและจัดการรางวัลเหรียญตรา (assertions) — เหรียญตราที่ออกให้ผู้รับเฉพาะ

จุดสิ้นสุดทั้งหมดต้องการการยืนยันตัวตนผ่านส่วนหัว 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	ไม่	วัตถุตัวกรอง (ดูด้านล่าง)
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

สร้างใบประกาศ PDF A4 พร้อมพิมพ์สำหรับรางวัล

GET /awards/{awardGuid}/pdf

ไม่ต้องการการยืนยันตัวตน — จุดสิ้นสุดนี้สาธารณะเพื่อให้ผู้รับสามารถดาวน์โหลดใบประกาศของตนเองได้

ตัวอย่าง

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

การตอบกลับเป็น PDF ไบนารีพร้อมส่วนหัว Content-Type: application/pdf

---

ติดตามเหตุการณ์รางวัล

บันทึกเหตุการณ์การมีส่วนร่วม (ดู, แชร์, ดาวน์โหลด, เพิ่ม 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 เดียวกันนับครั้งเดียวต่อ 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
    }
  }
}