API Lần cấp

Tạo và quản lý các lần cấp huy hiệu (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 lần cấp

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
blockchain	string	Không	Blockchain để xác thực on-chain. Chỉ hỗ trợ matchain. Có sẵn trên gói Pro.

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 lần cấp 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.
• Tham số blockchain chỉ có trên gói Pro.

---

Liệt kê lần cấp

Lấy các lần cấp 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 lần cấp

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 lần cấp

Gửi email thông báo cho người nhận về lần cấp 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ẻ lần cấp

Chia sẻ một lần cấp 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 lần cấp.

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 lần cấp

Ghi một sự kiện tương tác (xem, chia sẻ, tải, LinkedIn add). Được trang cấp 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ê lần cấp

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

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