เอกสารอ้างอิง Badges API: สร้าง ตรวจสอบ และเรียกดูตราสัญลักษณ์ดิจิทัล

จัดการเทมเพลตตราสัญลักษณ์ดิจิทัล ซึ่งเป็นข้อมูลรับรองที่คุณออกให้ผู้รับ

หากต้องการออกตราสัญลักษณ์ดิจิทัลนี้ให้ผู้รับจำนวนมากพร้อมกันโดยอัปโหลด CSV แทนการใช้ API ดู ข้อมูลรับรองแบบกลุ่ม

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

สร้างตราสัญลักษณ์ดิจิทัล

สร้างตราสัญลักษณ์ดิจิทัลใหม่ภายใต้ผู้ออกที่ผ่านการตรวจสอบแล้ว

POST /badges

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
name	string	ใช่	ชื่อตราสัญลักษณ์ดิจิทัล
description	string	ใช่	สิ่งที่ตราสัญลักษณ์ดิจิทัลนี้แสดงถึง
criteria	string	ใช่	สิ่งที่ผู้รับทำเพื่อให้ได้รับตราสัญลักษณ์ดิจิทัลนี้
image	string	ใช่	รูปภาพที่เข้ารหัส Base64 (PNG หรือ JPG)
issuerId	string	ใช่	ID ของผู้ออกที่ผ่านการตรวจสอบแล้ว
shareText	string	ไม่	ข้อความแชร์โซเชียลเริ่มต้นสำหรับตราสัญลักษณ์ดิจิทัลนี้ รองรับตัวแทน , และ หากไม่ระบุจะใช้ค่าเริ่มต้นในตัว
designJson	string	ไม่	เอกสารตัวออกแบบตราสัญลักษณ์ดิจิทัลที่ถูกซีเรียลไลซ์ เก็บไว้เพื่อให้แก้ไขตราสัญลักษณ์ดิจิทัลทีละเลเยอร์ได้ภายหลัง

ตัวอย่าง

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

การตอบกลับ

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

หมายเหตุ

• ผู้ออกต้องผ่านการตรวจสอบก่อนจึงจะสร้างตราสัญลักษณ์ดิจิทัลได้
• รูปภาพถูกจัดเก็บบน Amazon S3 และเผยแพร่ผ่าน CDN ทั่วโลกของเราภายใต้ URL แบบอิงเนื้อหาที่ไม่เปลี่ยนแปลง
• เมื่อมี badge class แล้ว ให้ออกให้ผู้รับโดยใช้ Credentials API

---

แสดงรายการตราสัญลักษณ์ดิจิทัล

ดึงตราสัญลักษณ์ดิจิทัลทั้งหมดที่คุณสร้างไว้

GET /badges

ตัวอย่าง

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

การตอบกลับ

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

ดึงข้อมูลตราสัญลักษณ์ดิจิทัล

ดึงตราสัญลักษณ์ดิจิทัลรายการเดียว รวมถึงข้อความแชร์และเอกสารตัวออกแบบตราสัญลักษณ์ดิจิทัลที่ซีเรียลไลซ์ (designJson) endpoint นี้ใช้โดยหน้าต่างแก้ไขตราสัญลักษณ์ดิจิทัลเพื่อกู้คืนแต่ละเลเยอร์ ส่วน endpoint แสดงรายการจะไม่ส่ง designJson เพื่อให้การตอบกลับมีขนาดเล็ก

GET /badges/{badgeId}

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
badgeId	string	ใช่	ID ของตราสัญลักษณ์ดิจิทัล (พารามิเตอร์ในพาธ)

ตัวอย่าง

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

การตอบกลับ

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

ข้อความแชร์จะรวมอยู่เสมอ รูปแบบรายการแบบเบา GET /badges?badgeId={id} ส่งคืนเอกสารเดียวกันโดยไม่มี designJson และจะรวมข้อความแชร์ก็ต่อเมื่อเรียกด้วย includeShareText=true

---

อัปเดตตราสัญลักษณ์ดิจิทัล

อัปเดตตราสัญลักษณ์ดิจิทัลที่มีอยู่ ระบบจะเปลี่ยนเฉพาะฟิลด์ที่คุณระบุ

PUT /badges/{badgeId}

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
badgeId	string	ใช่	ID ของตราสัญลักษณ์ดิจิทัล (พารามิเตอร์ในพาธ)
name	string	ไม่	ชื่อตราสัญลักษณ์ดิจิทัลใหม่
description	string	ไม่	คำอธิบายใหม่
criteria	string	ไม่	เกณฑ์ใหม่
image	string	ไม่	รูปภาพใหม่ที่เข้ารหัส Base64
designJson	string	ไม่	เอกสารตัวออกแบบตราสัญลักษณ์ดิจิทัลที่ซีเรียลไลซ์ฉบับใหม่

ตัวอย่าง

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

การตอบกลับ

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

อัปเดตข้อความแชร์

ตั้งข้อความที่กำหนดเองซึ่งจะแสดงเมื่อผู้รับแชร์ตราสัญลักษณ์ดิจิทัลนี้บนโซเชียลมีเดีย

PUT /badges/{badgeId}/share-text

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
badgeId	string	ใช่	ID ของตราสัญลักษณ์ดิจิทัล (พารามิเตอร์ในพาธ)
text	string	ใช่	ข้อความแชร์ (ไม่อนุญาตให้ใช้ HTML)

ตัวอย่าง

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

การตอบกลับ

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

ลบตราสัญลักษณ์ดิจิทัล

ลบตราสัญลักษณ์ดิจิทัล ตราสัญลักษณ์ดิจิทัลนั้นต้องไม่มีข้อมูลรับรองที่ออกไปแล้ว

DELETE /badges/{badgeId}

ตัวอย่าง

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

การตอบกลับ

ส่งคืนสตริงยืนยันแบบธรรมดา:

"badge has been deleted"

ข้อผิดพลาด

• 400 — ตราสัญลักษณ์ดิจิทัลยังมีข้อมูลรับรองที่ออกไปแล้ว: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — ไม่พบตราสัญลักษณ์ดิจิทัล