日本語
日本語
Appearance
クレデンシャル API
クレデンシャル（アサーション）、つまり特定の受領者に発行されたバッジを作成・管理します。
すべてのエンドポイントで、X-Api-Key ヘッダーによる認証が必要です。認証を参照してください。
クレデンシャルの作成
受領者にバッジを発行します。
1 人につき 1 回の API 呼び出しではなく、数百〜数千人の受領者へ一度に発行したい場合は、CSV アップロードに対応した UI 機能のクレデンシャルの一括発行をご利用ください。
POST /awardsパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
badgeId | string | はい | 発行するバッジの ID |
recipient | object | はい | 受領者の詳細（下記参照） |
recipient.name | string | はい | 受領者の氏名（5 文字以上） |
recipient.email | string | はい | 受領者のメールアドレス |
issuedOn | string | はい | ISO 8601 形式の発行日（例: 2025-01-15） |
expires | string | いいえ | ISO 8601 形式の有効期限 |
例
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"
}
}'レスポンス
json
{
"awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}注意事項
- 年間クレデンシャルプールから 1 件として消費されます（Free: 年 1,200 件、Starter: 年 12,000 件、Pro: 年 120,000 件）。プールは柔軟な年間の利用枠で、年内のいつでも、まとめて発行する場合も含めて自由に使え、アカウント登録の記念日にリセットされます。請求は引き続き月次で、年単位なのはクレデンシャルのクォータのみです。詳細はプランと請求を参照してください。
クレデンシャルの一覧
任意のフィルタリングとページネーションでクレデンシャルを取得します。
GET /awardsクエリパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
filter | JSON 文字列 | いいえ | フィルターオブジェクト（下記参照） |
lastEvaluatedKey | string | いいえ | 前回のレスポンスから得たページネーショントークン |
フィルターオブジェクト
filter パラメーターは、次のフィールドを持つ JSON 文字列を受け付けます。
| フィールド | 型 | 説明 |
|---|---|---|
badgeId | string | バッジ ID で絞り込みます。 |
search | string | 受領者の名前またはメールアドレスから検索する部分文字列（searchField を参照）。 |
searchField | string | name（デフォルト）または email のいずれか。検索対象の列を指定します。 |
lastEvaluatedKey によるページネーションは、フィルターの有無にかかわらず機能します。ページサイズは 50 です。
例 — すべてのクレデンシャルを一覧表示
bash
curl -X GET https://api.badges.ninja/awards \
-H "X-Api-Key: bws_your_api_key_here"例 — バッジで絞り込み
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"レスポンス
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..."
}レスポンスに lastEvaluatedKey が含まれている場合は、まだ結果が残っています。次のリクエストでクエリパラメーターとして渡すと、次のページを取得できます。
クレデンシャルのメール送信
受領者に、そのクレデンシャルに関するメール通知を送信します。
POST /awards/{awardId}/sendパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
awardId | string | はい | アワード ID（パスパラメーターおよびボディ） |
email | string | はい | 受領者のメールアドレス |
例
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"
}
}'レスポンス
確認用のプレーンな文字列を返します。
json
"email sent"クレデンシャルの共有
クレデンシャルを複数の受信者にメールで共有します。
POST /awards/{awardId}/shareパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
awardId | string | はい | アワード ID（パスパラメーターおよびボディ） |
recipients | string | はい | カンマ区切りのメールアドレス一覧 |
subject | string | はい | メールの件名 |
message | string | はい | メールの本文 |
例
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."
}
}'レスポンス
確認用のプレーンな文字列を返します。
json
"email sent"クレデンシャルの取り消し
発行したクレデンシャルを取り消します。ホスト型の Open Badges v2.0 アサーションに revoked: true（任意の理由付き）が設定され、どの検証者にもバッジが無効であることが分かります。クレデンシャルの記録は監査のために保持され、クレジットは返金されません。
取り消しは、そのクレデンシャルの Open Badges 3.0 Verifiable Credential にも反映されます。VC の credentialStatus が参照する W3C Bitstring Status List でそのアワードのビットが反転されるため、VC ウォレットでも検知できます。取り消し（Bitstring Status List）を参照してください。
POST /awards/{awardId}/revokeパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
awardId | string | はい | アワード ID（パスパラメーター） |
reason | string | いいえ | 取り消しの理由。500 文字に切り詰められます。 |
notify | boolean | いいえ | true の場合、クレデンシャルが取り消されたことを受領者にメールで通知します。デフォルトは false です。 |
例
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
}
}'レスポンス
json
{
"revoked": true,
"awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}すでに取り消されたクレデンシャルを再度取り消しても冪等です。通知を再送せず、同じレスポンスを返します。
一括取り消し
多数のクレデンシャルを一度に取り消すには、アワードごとにこのエンドポイントを呼び出す代わりに、action: "revoke" を指定した耐久性のある一括エンドポイントを使用します。
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 } }'{ "jobId", "total" } を返します。ジョブはサーバー側ですべての ID を取り消し（取り消し済みのものはスキップ）、再開も可能です。取り消し済みの ID と存在しない ID はスキップとして報告されます。
クレデンシャルの削除
発行したクレデンシャルを完全に削除します。取り消しと異なり、記録が完全に削除され、公開クレデンシャルページは 404 を返します。誤発行（例: 別の人への発行）など本当のミスに使用してください。実際のクレデンシャルには取り消しを推奨します。アサーションが取り消し済みとして検証可能なまま残るためです。クレジットは返金されません。
DELETE /awards/{awardId}パラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
awardId | string | はい | アワード ID（パスパラメーター） |
例
bash
curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
-H "X-Api-Key: bws_your_api_key_here"レスポンス
json
{
"deleted": true,
"awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}PDF 証明書のダウンロード
クレデンシャルの印刷用 A4 PDF 証明書を生成します。
GET /certify-badge/award/{awardGuid}/pdf認証は不要です。受領者が自分の証明書をダウンロードできるよう、このエンドポイントは公開されています。
例
bash
curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdfレスポンスは、Content-Type: application/pdf ヘッダー付きのバイナリ PDF です。
クレデンシャルイベントの記録
エンゲージメントイベントを記録します。公開クレデンシャルページがエンゲージメント統計を集計するために使用します。認証は不要です。
POST /certify-badge/award/{awardGuid}/eventパラメーター
このエンドポイントはボディを直接読み取ります（parameters ラッパーはありません）。
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
event | string | はい | view、share、download、click_linkedin_addtoprofile、click_pdf、click_verify のいずれか。 |
network | string | いいえ | event=share の場合のソーシャルネットワーク: linkedin、twitter、facebook、whatsapp、telegram、email、copy。 |
IP ごとの重複排除: 同じ IP からの同じイベントは 24 時間に 1 回だけカウントされます。
例
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"}'レスポンス
json
{
"ok": true
}クレデンシャル統計の取得
クレデンシャルの累積エンゲージメントカウンターを取得します。
GET /certify-badge/award/{awardGuid}/stats認証は不要です。
レスポンス
カウンターは、生のイベントタイプをキーとして返されます。totals にはイベントごとの合計数が入り、networks には network を伴うイベント（現在は share）のネットワーク別の内訳が入ります。記録された活動のないイベントは含まれません。
json
{
"totals": {
"view": 142,
"share": 16,
"download": 3,
"click_linkedin_addtoprofile": 4
},
"networks": {
"share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
}
}