API ข้อมูลรับรอง

สร้างและจัดการข้อมูลรับรอง (assertion) ซึ่งเป็นตราสัญลักษณ์ดิจิทัลที่ออกให้ผู้รับแต่ละราย

endpoint ทั้งหมดต้องยืนยันตัวตนผ่านเฮดเดอร์ X-Api-Key ดู การยืนยันตัวตน

สร้างข้อมูลรับรอง

ออกตราสัญลักษณ์ดิจิทัลให้ผู้รับ

ต้องการออกให้ผู้รับหลายร้อยหรือหลายพันคนพร้อมกัน แทนการเรียก API หนึ่งครั้งต่อหนึ่งคนหรือไม่ ใช้ฟีเจอร์ UI ข้อมูลรับรองแบบกลุ่ม ซึ่งรองรับการอัปโหลด CSV

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

ตัวอย่าง

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

การตอบกลับ

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

หมายเหตุ

• นับเป็นข้อมูลรับรองหนึ่งรายการจากโควตาข้อมูลรับรองรายปีของคุณ (Free: 1,200/ปี, Starter: 12,000/ปี, Pro: 120,000/ปี) โควตานี้เป็นสิทธิ์รายปีที่ยืดหยุ่น คุณใช้เมื่อไรก็ได้ตลอดทั้งปี รวมถึงใช้รวดเดียวจำนวนมาก และจะรีเซ็ตในวันครบรอบการลงทะเบียนบัญชีของคุณ การเรียกเก็บเงินยังคงเป็นรายเดือน มีเพียงโควตาข้อมูลรับรองเท่านั้นที่เป็นรายปี ดูรายละเอียดที่ แผนและการเรียกเก็บเงิน

---

แสดงรายการข้อมูลรับรอง

ดึงข้อมูลรับรองพร้อมตัวกรองและการแบ่งหน้าแบบไม่บังคับ

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"

การตอบกลับ

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "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 ของข้อมูลรับรอง (พารามิเตอร์ใน path และ body)
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"
    }
  }'

การตอบกลับ

ส่งคืนสตริงยืนยันแบบข้อความธรรมดา

"email sent"

---

แชร์ข้อมูลรับรอง

แชร์ข้อมูลรับรองให้ผู้รับหลายคนทางอีเมล

POST /awards/{awardId}/share

พารามิเตอร์

พารามิเตอร์	ชนิด	จำเป็น	คำอธิบาย
awardId	string	ใช่	ID ของข้อมูลรับรอง (พารามิเตอร์ใน path และ body)
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."
    }
  }'

การตอบกลับ

ส่งคืนสตริงยืนยันแบบข้อความธรรมดา

"email sent"

---

เพิกถอนข้อมูลรับรอง

เพิกถอนข้อมูลรับรองที่คุณออกไป assertion Open Badges v2.0 ที่โฮสต์ไว้จะถูกทำเครื่องหมาย revoked: true (พร้อมเหตุผลแบบไม่บังคับ) เพื่อให้ผู้ตรวจสอบทุกรายเห็นว่าตราสัญลักษณ์นี้ใช้ไม่ได้อีกต่อไป ระบบจะเก็บบันทึกข้อมูลรับรองไว้เพื่อการตรวจสอบย้อนหลัง และไม่มีการคืนเครดิต

การเพิกถอนยังส่งต่อไปยัง Open Badges 3.0 Verifiable Credential ของข้อมูลรับรองด้วย โดยบิตของรางวัลนั้นจะถูกพลิกใน W3C Bitstring Status List ที่ credentialStatus ของ VC อ้างอิงอยู่ กระเป๋า VC จึงตรวจพบได้เช่นกัน ดู การเพิกถอน (Bitstring Status List)

POST /awards/{awardId}/revoke

พารามิเตอร์

พารามิเตอร์	ชนิด	จำเป็น	คำอธิบาย
awardId	string	ใช่	ID ของข้อมูลรับรอง (พารามิเตอร์ใน path)
reason	string	ไม่	เหตุผลในการเพิกถอน ตัดให้เหลือ 500 ตัวอักษร
notify	boolean	ไม่	เมื่อเป็น true ระบบจะส่งอีเมลแจ้งผู้รับว่าข้อมูลรับรองของพวกเขาถูกเพิกถอน ค่าเริ่มต้นคือ false

ตัวอย่าง

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

การตอบกลับ

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

การเพิกถอนข้อมูลรับรองที่ถูกเพิกถอนไปแล้วเป็นแบบ idempotent โดยจะส่งคืนการตอบกลับเดิมโดยไม่ส่งการแจ้งเตือนซ้ำ

เพิกถอนแบบกลุ่ม

หากต้องการเพิกถอนข้อมูลรับรองจำนวนมากพร้อมกัน ให้ใช้ endpoint แบบกลุ่มที่ทนทานพร้อม action: "revoke" แทนการเรียก endpoint นี้ทีละรางวัล

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

endpoint จะส่งคืน { "jobId", "total" } งานจะเพิกถอนทุก ID ที่ฝั่งเซิร์ฟเวอร์ (ข้ามรายการที่ถูกเพิกถอนไปแล้ว) และสามารถทำต่อได้ ID ที่ถูกเพิกถอนไปแล้วและ ID ที่ไม่มีอยู่จริงจะถูกรายงานว่าข้าม

---

ลบข้อมูลรับรอง

ลบข้อมูลรับรองที่คุณออกไปอย่างถาวร ต่างจากการเพิกถอน การลบจะนำบันทึกออกทั้งหมด และหน้าข้อมูลรับรองสาธารณะจะส่งคืน 404 ใช้เมื่อเกิดความผิดพลาดจริง ๆ (เช่น ออกให้ผิดคน) ส่วนข้อมูลรับรองจริงควรเลือก เพิกถอน เพื่อให้ assertion ยังคงตรวจสอบได้ว่าถูกเพิกถอน ไม่มีการคืนเครดิต

DELETE /awards/{awardId}

พารามิเตอร์

พารามิเตอร์	ชนิด	จำเป็น	คำอธิบาย
awardId	string	ใช่	ID ของข้อมูลรับรอง (พารามิเตอร์ใน path)

ตัวอย่าง

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

การตอบกลับ

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

ดาวน์โหลดใบรับรอง PDF

สร้างใบรับรอง PDF ขนาด A4 พร้อมพิมพ์สำหรับข้อมูลรับรอง

GET /certify-badge/award/{awardGuid}/pdf

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

ตัวอย่าง

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

การตอบกลับคือไฟล์ PDF แบบไบนารีพร้อมเฮดเดอร์ Content-Type: application/pdf

---

บันทึกเหตุการณ์ข้อมูลรับรอง

บันทึกเหตุการณ์การมีส่วนร่วม หน้าข้อมูลรับรองสาธารณะใช้เพื่อเติมสถิติการมีส่วนร่วม ไม่ต้องยืนยันตัวตน

POST /certify-badge/award/{awardGuid}/event

พารามิเตอร์

endpoint นี้อ่าน body โดยตรง (ไม่มี wrapper parameters)

พารามิเตอร์	ชนิด	จำเป็น	คำอธิบาย
event	string	ใช่	หนึ่งใน view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify
network	string	ไม่	เมื่อ event=share คือเครือข่ายโซเชียล: linkedin, twitter, facebook, whatsapp, telegram, email, copy

การกันเหตุการณ์ซ้ำต่อ IP: เหตุการณ์เดียวกันจาก IP เดียวกันจะนับเพียงครั้งเดียวภายใน 24 ชั่วโมง

ตัวอย่าง

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

การตอบกลับ

{
  "ok": true
}

---

ดูสถิติข้อมูลรับรอง

ดึงตัวนับการมีส่วนร่วมสะสมของข้อมูลรับรอง

GET /certify-badge/award/{awardGuid}/stats

ไม่ต้องยืนยันตัวตน

การตอบกลับ

ตัวนับจะถูกส่งคืนโดยใช้ประเภทเหตุการณ์ดิบเป็นคีย์ totals เก็บจำนวนรวมของแต่ละเหตุการณ์ ส่วน networks แจกแจงการแบ่งตามเครือข่ายสำหรับเหตุการณ์ที่มี network (ปัจจุบันคือ share) เหตุการณ์ที่ไม่มีกิจกรรมที่บันทึกไว้จะไม่ปรากฏ

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}