ออก Open Badges ผ่าน Badges Ninja REST API: คู่มือเริ่มต้นฉบับย่อ

โปรแกรมรับรองความสามารถส่วนใหญ่ไม่เคยต้องใช้ API เลย ถ้าคุณสอนหลักสูตรที่มีผู้สำเร็จการศึกษาปีละไม่กี่ร้อยคน แดชบอร์ดก็ทำได้ทุกอย่าง คุณออกแบบตราสัญลักษณ์ดิจิทัลในตัวออกแบบภาพ อัปโหลดไฟล์ CSV แล้วผู้รับทุกคนจะได้หน้าตรวจสอบและใบรับรอง PDF ถ้านี่คือสถานการณ์ของคุณ ให้เริ่มที่ วิธีออก Open Badges จาก CSV แล้วค่อยกลับมาอ่านทีหลัง

API จะคุ้มค่าเมื่อระบบอื่นต้องเป็นฝ่ายออกข้อมูลรับรอง เช่น แพลตฟอร์มการเรียนของคุณทำเครื่องหมายว่าจบคอร์สแล้ว เครื่องมือลงทะเบียนของคุณปิดกิจกรรม หรือระบบ HR ของคุณบันทึกว่าจบโมดูลด้านการปฏิบัติตามกฎระเบียบ ในกรณีเหล่านี้ไม่มีใครอยากส่งออกสเปรดชีตทุกสิ้นสัปดาห์ การเรียก HTTP เพียงครั้งเดียวในจังหวะที่เรียนจบง่ายกว่ามาก และผู้รับจะได้ตราสัญลักษณ์ดิจิทัลขณะที่ความสำเร็จยังสดใหม่

คู่มือฉบับย่อนี้พาคุณเดินครบทั้งเส้นทางด้วยการเรียกสี่ครั้ง ได้แก่ รับคีย์ สร้างผู้ออก สร้างตราสัญลักษณ์ดิจิทัล และมอบให้ผู้รับ จากนั้นเราจะดูวิธีส่งลิงก์ตรวจสอบให้ผู้รับและเช็กผลลัพธ์ รูปแบบคำขอทุกแบบด้านล่างมาจาก handler ที่ใช้งานจริง คุณจึงคัดลอกไปรันได้เลย

สิ่งที่ต้องมีก่อนเริ่ม

• บัญชีฟรีที่ badges.ninja แผน Free เพียงพอสำหรับบทแนะนำนี้ ซึ่งรวมผู้ออก 2 ราย ตราสัญลักษณ์ดิจิทัล 5 รายการ ที่นั่ง 2 ที่ และ API key 1 ชุด
• API key หนึ่งชุด ซึ่งสร้างจากแดชบอร์ด
• ไฟล์ PNG หรือ JPG สำหรับรูปตราสัญลักษณ์ หรือตราสัญลักษณ์ที่คุณออกแบบไว้ในตัวออกแบบภาพ

Base URL สำหรับทุกอย่างคือ https://api.badges.ninja

ขั้นตอนที่ 1: สร้าง API key

ลงชื่อเข้าใช้ เปิด API Keys ในแถบด้านข้าง แล้วคลิก Create API Key ตั้งชื่อที่บอกว่าคีย์นี้จะอยู่ที่ไหน เช่น “LMS integration” เพื่อให้คุณแยกคีย์ออกจากกันได้เมื่อต้องหมุนเวียนคีย์ภายหลัง

คีย์จะแสดงเพียงครั้งเดียวเท่านั้น ให้คัดลอกไปไว้ในตัวจัดการความลับหรือตัวแปรสภาพแวดล้อมทันที คีย์มีรูปแบบเป็น bws_ ตามด้วยอักขระเลขฐานสิบหก 32 ตัว และคุณส่งคีย์ในเฮดเดอร์ X-Api-Key ทุกคำขอ การเพิกถอนคีย์จากหน้าจอเดียวกันมีผลทันที

นิสัยดี ๆ ไม่กี่ข้อที่ช่วยลดปัญหาภายหลัง

• ห้ามใส่คีย์ในโค้ดฝั่งหน้าบ้านหรือที่เก็บโค้ดสาธารณะ ให้เรียก API จากเซิร์ฟเวอร์ ฟังก์ชันแบบ serverless หรือเครื่องมืออัตโนมัติ
• ใช้หนึ่งคีย์ต่อหนึ่งการเชื่อมต่อ ถ้าคีย์หนึ่งรั่วไหล คุณเพียงเพิกถอนการเชื่อมต่อเดียวแทนที่จะเพิกถอนทั้งหมด
• แดชบอร์ดยังรับเซสชันที่คุณลงชื่อเข้าใช้ไว้ด้วย (Cognito JWT ที่ส่งเป็น Authorization: Bearer) แต่สำหรับสคริปต์และการเชื่อมต่อ API key คือเครื่องมือที่เหมาะสม

ตัวอย่างทั้งหมดด้านล่างอ่านคีย์จากตัวแปรสภาพแวดล้อมชื่อ 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"
}

เก็บค่านั้นไว้ตามที่ได้รับกลับมาทุกประการ เพราะเป็นอินพุตของขั้นตอนถัดไป

การตรวจสอบผู้ออก

ตราสัญลักษณ์ดิจิทัลสร้างได้เฉพาะภายใต้ผู้ออกที่ผ่านการตรวจสอบแล้ว การตรวจสอบทำงานดังนี้

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

ดังนั้นสำหรับบทแนะนำนี้ ให้ใช้อีเมลเดียวกับที่คุณสมัครไว้

ขั้นตอนที่ 3: สร้างตราสัญลักษณ์ดิจิทัล

ตราสัญลักษณ์ดิจิทัลคือแม่แบบที่ใช้ซ้ำได้ ประกอบด้วยชื่อ คำอธิบาย เกณฑ์ และรูปภาพ การมอบทุกครั้งที่คุณออกในภายหลังจะอ้างอิงกลับมาที่แม่แบบนี้

คำขอเป็น JSON ธรรมดา รูปภาพส่งเป็นสตริง base64 จึงไม่ต้องปวดหัวกับการอัปโหลดแบบ multipart คำนำหน้า data URL เช่น data:image/png;base64, ใช้ได้และจะถูกตัดออกให้

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>" } รูปภาพถูกจัดเก็บถาวร และตอนนี้ตราสัญลักษณ์ดิจิทัลเป็น BadgeClass ของ Open Badge v2.0 ที่ใครก็ดึงข้อมูลได้

ควรสร้างตราสัญลักษณ์ดิจิทัลในโค้ดหรือไม่?

โดยทั่วไปไม่ การออกแบบตราสัญลักษณ์ดิจิทัลเป็นงานสร้างสรรค์ และตัวออกแบบภาพ (แม่แบบกว่า 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 หรือสตริงวันที่ ISO เช่น 2026-09-28
• expires เป็นฟิลด์เสริมและรับรูปแบบเดียวกัน

เมื่อสำเร็จจะได้ HTTP 200 พร้อมเนื้อหาที่มี awardId อีเมลของผู้รับถูกเก็บเป็นแฮช SHA-256 ในข้อมูล Open Badge ดังนั้น JSON สาธารณะจะไม่เปิดเผยอีเมลนั้น

ขั้นตอนที่ 5: หาหน้าตรวจสอบและ JSON ของ Open Badge

การตอบกลับของการมอบให้ตัวระบุแก่คุณ ไม่ใช่ลิงก์สำเร็จรูป ตัวระบุลงท้ายด้วย 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 ที่โฮสต์ไว้ เนื่องจากเป็นข้อมูล Open Badges มาตรฐาน เครื่องมือใดที่เข้าใจรูปแบบนี้ก็อ่านได้ ความสามารถในการพกพานี้คือเหตุผลที่ควรเลือก Open Badges แทน PDF ที่เป็นระบบปิด Open Badges vs PDF certificates เจาะลึกข้อแลกเปลี่ยนนี้

ผู้รับได้รับข้อมูลรับรองอย่างไร

การสร้างการมอบเป็นคนละเรื่องกับการแจ้งผู้รับ ผู้รับเปิดข้อมูลรับรองของตนได้ผ่านพอร์ทัลผู้รับที่ badges.ninja/me ซึ่งลงชื่อเข้าใช้ด้วย magic link ไม่ต้องใช้รหัสผ่าน และเผยแพร่โปรไฟล์สาธารณะได้ที่ badges.ninja/u/<handle> จากหน้าตรวจสอบ พวกเขาเพิ่มตราสัญลักษณ์ดิจิทัลลง LinkedIn ดาวน์โหลดใบรับรอง PDF หรือแชร์ลิงก์ได้

สำหรับการทดสอบสองสามครั้งแรก ลองมอบให้ตัวคุณเองด้วยอีเมลของคุณ แล้วเดินผ่านประสบการณ์ของผู้รับ เป็นวิธีที่เร็วที่สุดที่จะสังเกตเห็นเรื่องอย่างคำอธิบายตราสัญลักษณ์ดิจิทัลที่อ่านแล้วแปร่ง ๆ

การจัดการข้อผิดพลาดที่ไม่ปวดหัว

API ใช้รหัสสถานะ HTTP ธรรมดา รหัสที่คุณจะเจอมีดังนี้

เคล็ดลับเชิงปฏิบัติสองข้อ ข้อแรก ให้ถือว่า 400 เป็นปัญหาของข้อมูลและบันทึกเนื้อหาการตอบกลับไว้ เพราะระบุฟิลด์ที่ผิด ข้อสอง ทำให้การเชื่อมต่อของคุณเป็น idempotent ในฝั่งของคุณ โดยเก็บ awardId ไว้คู่กับระเบียนการเรียนจบในฐานข้อมูลของคุณ และตรวจสอบก่อนเรียก API อีกครั้ง วิธีนี้ทำให้ webhook ที่ถูกส่งซ้ำหรืองานที่รันใหม่ไม่ออกข้อมูลรับรองให้คนเดียวกันสองครั้ง

ประกอบทุกอย่างเข้าด้วยกันในการเชื่อมต่อจริง

การเชื่อมต่อแบบทั่วไปเป็นดังนี้

1. ออกแบบตราสัญลักษณ์ดิจิทัลในแดชบอร์ด หนึ่งอันต่อคอร์สหรือหลักไมล์ และจด ID ของแต่ละอันไว้
2. เก็บการจับคู่จากคอร์สไปยัง ID ของตราสัญลักษณ์ดิจิทัลไว้ในระบบของคุณ
3. เมื่อผู้เรียนจบคอร์ส เซิร์ฟเวอร์ของคุณเรียก POST /awards พร้อมชื่อ อีเมล และวันที่เรียนจบ
4. บันทึก awardId ที่ได้กลับมาไว้กับระเบียนการเรียนจบ
5. แสดงลิงก์ตรวจสอบในผลิตภัณฑ์ของคุณเอง เพื่อให้ผู้เรียนเห็นโดยไม่ต้องออกไปที่อื่น

ถ้าคุณไม่อยากเขียนโค้ด การเรียกเดียวกันนี้ใช้ได้จากเครื่องมืออัตโนมัติใดก็ได้ที่ส่งคำขอ HTTP พร้อมเนื้อหา JSON และเฮดเดอร์กำหนดเองได้ ชี้ไปที่ https://api.badges.ninja/awards แล้วแมปฟิลด์จากฟอร์มหรือสเปรดชีตของคุณเข้ากับ badgeId, recipient.name, recipient.email และ issuedOn

แผนและขีดจำกัดที่ควรรู้

API ใช้ได้ในทุกแผน คุณไม่ต้องจ่ายเพิ่มเพื่อปลดล็อก แผน Free ($0) ครอบคลุมผู้ออก 2 ราย ตราสัญลักษณ์ดิจิทัล 5 รายการ ที่นั่ง 2 ที่ API key 1 ชุด และข้อมูลรับรอง 1,200 รายการต่อปี Starter ราคา $9 ต่อเดือน และ Pro ราคา $29 ต่อเดือน พร้อมขีดจำกัดที่สูงขึ้น ตรวจดู หน้าราคา เพื่อดูตัวเลขล่าสุดก่อนวางแผนขนาดการใช้งาน ถ้าคุณกำลังเปรียบเทียบค่าบริการเข้าถึง API ของแพลตฟอร์มอื่น Credly alternative วางต้นทุนเทียบกันให้เห็นชัด

ไปต่อที่ไหน

• เอกสารอ้างอิง endpoint ฉบับเต็มอยู่ใน เอกสาร API ซึ่งมีให้ใน 40 ภาษา
• สำหรับรายละเอียดการยืนยันตัวตนและการจัดการคีย์ ดู คู่มือการยืนยันตัวตน
• สำหรับรหัสข้อผิดพลาดแบบละเอียด ดู เอกสารอ้างอิงข้อผิดพลาด
• เมื่อการเรียกทีละครั้งไม่พออีกต่อไป ให้ใช้การมอบแบบกลุ่มในแดชบอร์ด อัปโหลด CSV แล้วหยุดชั่วคราวหรือเริ่มต่อได้ตามต้องการ

การมอบสำเร็จครั้งแรกคือส่วนที่ยากที่สุด หลังจากนั้นที่เหลือเป็นเพียงการนำการเรียกเดิมไปต่อกับจุดที่บันทึกความสำเร็จอยู่แล้ว

พร้อมออกข้อมูลรับรองที่ตรวจสอบได้ชุดแรกของคุณหรือยัง? เริ่มฟรีที่ badges.ninja — ตัวออกแบบภาพ หน้าตรวจสอบสาธารณะ ใบรับรอง PDF เอาต์พุต Open Badge v2.0 ไม่ต้องใช้บัตรเครดิต