API Chứng chỉ

Tạo và quản lý chứng chỉ (assertion) — huy hiệu được cấp cho từng người nhận cụ thể.

Tất cả các endpoint đều yêu cầu xác thực qua header X-Api-Key. Xem Xác thực.

Tạo chứng chỉ

Cấp một huy hiệu cho người nhận.

Cần cấp cho hàng trăm hoặc hàng nghìn người nhận cùng lúc thay vì gọi API một lần cho mỗi người? Hãy dùng tính năng giao diện Chứng chỉ hàng loạt, cho phép tải lên tệp CSV.

POST /awards

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
`badgeId`	string	Có	ID huy hiệu cần cấp
`recipient`	object	Có	Thông tin người nhận (xem bên dưới)
`recipient.name`	string	Có	Họ tên đầy đủ của người nhận (tối thiểu 5 ký tự)
`recipient.email`	string	Có	Địa chỉ email của người nhận
`issuedOn`	string	Có	Ngày cấp theo định dạng ISO 8601 (ví dụ `2025-01-15`)
`expires`	string	Không	Ngày hết hạn theo định dạng ISO 8601

Ví dụ

bash

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

Phản hồi

json

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

Ghi chú

Được tính là một chứng chỉ trong quỹ chứng chỉ hằng năm của bạn (Free: 1.200/năm, Starter: 12.000/năm, Pro: 120.000/năm). Quỹ này là hạn mức hằng năm linh hoạt — bạn có thể dùng bất cứ lúc nào trong năm, kể cả theo từng đợt lớn — và được làm mới vào ngày kỷ niệm đăng ký tài khoản của bạn. Việc thanh toán vẫn theo tháng; chỉ hạn mức chứng chỉ là theo năm. Xem Gói và thanh toán để biết chi tiết.

Liệt kê chứng chỉ

Lấy danh sách chứng chỉ với tùy chọn lọc và phân trang.

GET /awards

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`filter`	JSON string	Không	Đối tượng bộ lọc (xem bên dưới)
`lastEvaluatedKey`	string	Không	Token phân trang từ phản hồi trước

Đối tượng bộ lọc

Tham số filter nhận một chuỗi JSON với các trường sau:

Trường	Kiểu	Mô tả
`badgeId`	string	Lọc theo ID huy hiệu.
`search`	string	Chuỗi con để tìm trong tên hoặc email của người nhận (xem `searchField`).
`searchField`	string	`name` (mặc định) hoặc `email` — cột cần tìm kiếm.

Phân trang qua lastEvaluatedKey hoạt động cả khi có và không có bộ lọc. Kích thước trang là 50.

Ví dụ — Liệt kê tất cả chứng chỉ

bash

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

Ví dụ — Lọc theo huy hiệu

bash

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"

Phản hồi

json

{
  "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..."
}

Nếu phản hồi có lastEvaluatedKey, nghĩa là còn kết quả khác. Hãy truyền nó làm tham số truy vấn trong yêu cầu tiếp theo để lấy trang kế tiếp.

Gửi email chứng chỉ

Gửi email thông báo cho người nhận về chứng chỉ của họ.

POST /awards/{awardId}/send

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
`awardId`	string	Có	ID giải thưởng (tham số đường dẫn và nội dung body)
`email`	string	Có	Địa chỉ email của người nhận

Ví dụ

bash

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

Phản hồi

Trả về một chuỗi xác nhận thuần:

json

"email sent"

Chia sẻ chứng chỉ

Chia sẻ chứng chỉ với nhiều người nhận qua email.

POST /awards/{awardId}/share

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
`awardId`	string	Có	ID giải thưởng (tham số đường dẫn và nội dung body)
`recipients`	string	Có	Danh sách địa chỉ email phân tách bằng dấu phẩy
`subject`	string	Có	Dòng tiêu đề email
`message`	string	Có	Nội dung email

Ví dụ

bash

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

Phản hồi

Trả về một chuỗi xác nhận thuần:

json

"email sent"

Thu hồi chứng chỉ

Thu hồi một chứng chỉ mà bạn đã cấp. Assertion Open Badges v2.0 được lưu trữ sẽ được đánh dấu revoked: true (kèm lý do tùy chọn) để mọi công cụ xác minh đều thấy huy hiệu không còn hiệu lực. Bản ghi chứng chỉ được giữ lại để phục vụ kiểm toán và không hoàn lại tín dụng.

Việc thu hồi cũng lan sang Verifiable Credential Open Badges 3.0 của chứng chỉ: bit của giải thưởng được lật trong W3C Bitstring Status List được tham chiếu bởi credentialStatus của VC, nên các ví VC cũng phát hiện được. Xem Thu hồi (Bitstring Status List).

POST /awards/{awardId}/revoke

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
`awardId`	string	Có	ID giải thưởng (tham số đường dẫn)
`reason`	string	Không	Lý do thu hồi. Bị cắt ngắn còn 500 ký tự.
`notify`	boolean	Không	Khi là `true`, gửi email cho người nhận thông báo chứng chỉ của họ đã bị thu hồi. Mặc định là `false`.

Ví dụ

bash

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

Phản hồi

json

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

Thu hồi một chứng chỉ đã bị thu hồi là thao tác idempotent — trả về cùng phản hồi mà không gửi lại thông báo.

Thu hồi hàng loạt

Để thu hồi nhiều chứng chỉ cùng lúc, hãy dùng endpoint hàng loạt bền vững với action: "revoke" thay vì gọi endpoint này cho từng giải thưởng:

bash

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 trả về { "jobId", "total" }; tác vụ thu hồi từng ID phía máy chủ (bỏ qua các ID đã bị thu hồi) và có thể tiếp tục khi bị gián đoạn. Các ID đã bị thu hồi và không tồn tại được báo cáo là bị bỏ qua.

Xóa chứng chỉ

Xóa vĩnh viễn một chứng chỉ mà bạn đã cấp. Khác với thu hồi, thao tác này xóa hoàn toàn bản ghi và trang chứng chỉ công khai sẽ trả về 404. Hãy dùng cho những sai sót thực sự (ví dụ cấp nhầm người); với các chứng chỉ thật, nên ưu tiên thu hồi để assertion vẫn xác minh được là đã thu hồi. Không hoàn lại tín dụng.

DELETE /awards/{awardId}

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
`awardId`	string	Có	ID giải thưởng (tham số đường dẫn)

Ví dụ

bash

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

Phản hồi

json

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

Tải chứng nhận PDF

Tạo chứng nhận PDF khổ A4 sẵn sàng để in cho một chứng chỉ.

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

Không yêu cầu xác thực — endpoint này công khai để người nhận có thể tự tải chứng nhận của mình.

Ví dụ

bash

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

Phản hồi là tệp PDF nhị phân với header Content-Type: application/pdf.

Ghi nhận sự kiện chứng chỉ

Ghi lại một sự kiện tương tác. Được trang chứng chỉ công khai dùng để tạo số liệu thống kê tương tác. Không yêu cầu xác thực.

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

Tham số

Endpoint này đọc trực tiếp body (không có lớp bọc parameters).

Tham số	Kiểu	Bắt buộc	Mô tả
`event`	string	Có	Một trong `view`, `share`, `download`, `click_linkedin_addtoprofile`, `click_pdf`, `click_verify`.
`network`	string	Không	Khi `event=share`, là mạng xã hội: `linkedin`, `twitter`, `facebook`, `whatsapp`, `telegram`, `email`, `copy`.

Chống trùng lặp theo IP: cùng một sự kiện từ cùng một IP chỉ được tính một lần trong 24 giờ.

Ví dụ

bash

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

Phản hồi

json

{
  "ok": true
}

Lấy thống kê chứng chỉ

Lấy các bộ đếm tương tác tích lũy của một chứng chỉ.

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

Không yêu cầu xác thực.

Phản hồi

Các bộ đếm được trả về theo loại sự kiện thô. totals chứa tổng số cho từng sự kiện; networks phân tách theo từng mạng đối với các sự kiện có network (hiện là share). Các sự kiện không có hoạt động nào được ghi nhận sẽ đơn giản là không xuất hiện.

json

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

API Chứng chỉ ​

Tạo chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Ghi chú ​

Liệt kê chứng chỉ ​

Tham số truy vấn ​

Đối tượng bộ lọc ​

Ví dụ — Liệt kê tất cả chứng chỉ ​

Ví dụ — Lọc theo huy hiệu ​

Phản hồi ​

Gửi email chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Chia sẻ chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Thu hồi chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Thu hồi hàng loạt ​

Xóa chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Tải chứng nhận PDF ​

Ví dụ ​

Ghi nhận sự kiện chứng chỉ ​

Tham số ​

Ví dụ ​

Phản hồi ​

Lấy thống kê chứng chỉ ​

Phản hồi ​

API Chứng chỉ

Tạo chứng chỉ

Tham số

Ví dụ

Phản hồi

Ghi chú

Liệt kê chứng chỉ

Tham số truy vấn

Đối tượng bộ lọc

Ví dụ — Liệt kê tất cả chứng chỉ

Ví dụ — Lọc theo huy hiệu

Phản hồi

Gửi email chứng chỉ

Tham số

Ví dụ

Phản hồi

Chia sẻ chứng chỉ

Tham số

Ví dụ

Phản hồi

Thu hồi chứng chỉ

Tham số

Ví dụ

Phản hồi

Thu hồi hàng loạt

Xóa chứng chỉ

Tham số

Ví dụ

Phản hồi

Tải chứng nhận PDF

Ví dụ

Ghi nhận sự kiện chứng chỉ

Tham số

Ví dụ

Phản hồi

Lấy thống kê chứng chỉ

Phản hồi