Xác minh công khai

Các endpoint này là công khai và không yêu cầu xác thực. Chúng cho phép bất kỳ ai xác minh chứng chỉ huy hiệu và truy xuất dữ liệu JSON Open Badge v2.0.

Tất cả endpoint đều tương đối so với https://api.badges.ninja.

Lấy tổ chức cấp

Truy xuất JSON hồ sơ tổ chức cấp (Issuer Profile) Open Badge v2.0 của một tổ chức cấp.

GET /certify-badge/issuer/{guid}

Ví dụ

curl https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Phản hồi

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Issuer",
  "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "name": "Acme Academy",
  "url": "https://acme.example.com",
  "email": "badges@acme.example.com",
  "verification": {
    "type": "hosted",
    "allowedOrigins": "api.badges.ninja"
  }
}

---

Lấy huy hiệu

Truy xuất JSON BadgeClass Open Badge v2.0 của một huy hiệu.

GET /certify-badge/badge/{guid}

Ví dụ

curl https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901

Phản hồi

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "BadgeClass",
  "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 with a score of 80% or higher"
  },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-..."
}

---

Lấy chứng chỉ

Truy xuất JSON Assertion Open Badge v2.0 của một chứng chỉ.

GET /certify-badge/award/{guid}

Ví dụ

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

Phản hồi

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
  "recipient": {
    "type": "email",
    "hashed": true,
    "identity": "sha256$..."
  },
  "badge": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "issuedOn": "2025-01-15T00:00:00.000Z",
  "verification": {
    "type": "hosted"
  },
  "revoked": false
}

Nếu chứng chỉ đã bị thu hồi, assertion sẽ có "revoked": true và, khi có lý do được cung cấp, thêm chuỗi "revocationReason":

{
  "revoked": true,
  "revocationReason": "Issued in error"
}

Đây là cách Open Badges 2.0 thể hiện việc thu hồi. Việc thu hồi này cũng được thể hiện trong Verifiable Credential Open Badges 3.0 của chứng chỉ — xem Thu hồi (Bitstring Status List).

Ghi chú

• Email của người nhận được băm (SHA-256) để bảo mật quyền riêng tư, theo đặc tả Open Badge.
• Phản hồi được lưu đệm trong 5 phút (Cache-Control: public, max-age=300). Chứng chỉ đã bị thu hồi dùng bộ đệm ngắn hơn là 30 giây (max-age=30) để việc thu hồi được lan truyền nhanh chóng.

---

Lấy văn bản chia sẻ của chứng chỉ

Truy xuất văn bản chia sẻ tùy chỉnh cho huy hiệu của một chứng chỉ.

GET /certify-badge/award/{guid}/share-text

Ví dụ

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

Phản hồi

{
  "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
}

Nếu chưa đặt văn bản chia sẻ tùy chỉnh, một thông điệp mặc định sẽ được trả về.

---

Gửi email chứng chỉ (công khai)

Gửi email thông báo chứng chỉ từ endpoint công khai. Endpoint này được trang chia sẻ công khai sử dụng.

POST /certify-badge/award/{guid}/send-email

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
recipients	string	Có	Danh sách địa chỉ email, phân tách bằng dấu phẩy
message	string	Không	Thông điệp tùy chỉnh đưa vào email

Ví dụ

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "recipients": "colleague@example.com",
      "message": "Check out this badge!"
    }
  }'

Phản hồi

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

Đây là endpoint duy nhất bọc kết quả trong phong bì { "statusCode", "info" }. Mọi endpoint khác trả về dữ liệu trực tiếp.

---

Xác minh tổ chức cấp

Xác minh một tổ chức cấp bằng cách nhấp vào liên kết xác minh được gửi tới email của tổ chức cấp. Thông thường bạn truy cập qua liên kết trong email xác minh chứ không gọi trực tiếp.

GET /certify-badge/verify-issuer/{guid}/{code}

Tham số

Tham số	Kiểu	Mô tả
guid	string	GUID của tổ chức cấp
code	string	Mã xác minh

Phản hồi

Trả về một trang HTML xác nhận việc xác minh thành công hay thất bại. Endpoint này được thiết kế để mở trong trình duyệt.