API Chứng chỉ

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

Tất cả các điểm cuối cần 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.

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ó	Email 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ụ

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

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

Ghi chú

• Tính là một chứng chỉ trong hạn mức hàng tháng của bạn (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Hạn mức đặt lại mỗi kỳ thanh toán.

---

Liệt kê chứng chỉ

Lấy các 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	chuỗi JSON	Không	Đối tượng 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 lọc

Tham số filter chấp nhận chuỗi JSON với các trường này:

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 người nhận (xem searchField).
searchField	string	name (mặc định) hoặc email — cột cần tìm.

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

Ví dụ — Liệt kê mọi chứng chỉ

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

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

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "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 có lastEvaluatedKey trong phản hồi, còn thêm kết quả. Truyền nó làm tham số truy vấn trong yêu cầu tiếp theo để lấy trang sau.

---

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 lần cấp (tham số đường dẫn và thân)
email	string	Có	Email người nhận

Ví dụ

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

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

---

Chia sẻ chứng chỉ

Chia sẻ một 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 lần cấp (tham số đường dẫn và thân)
recipients	string	Có	Danh sách email phân cách bằng dấu phẩy
subject	string	Có	Dòng tiêu đề email
message	string	Có	Nội dung email

Ví dụ

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

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

Tải chứng nhận PDF

Tạo một tệp PDF A4 sẵn in cho một chứng chỉ.

GET /awards/{awardGuid}/pdf

Không cần xác thực — điểm cuối này công khai để người nhận có thể tự tải chứng nhận.

Ví dụ

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

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

---

Theo dõi sự kiện chứng chỉ

Ghi một sự kiện tương tác (xem, chia sẻ, tải, LinkedIn add). Được trang chứng chỉ công khai dùng để điền thống kê tương tác. Không cần xác thực.

POST /awards/{awardGuid}/event

Tham số

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

Chống lặp theo IP: cùng loại sự kiện từ cùng IP được tính một lần mỗi 24 giờ.

Ví dụ

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

---

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

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

GET /awards/{awardGuid}/stats

Không cần xác thực.

Phản hồi

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}