授与 API

バッジの授与(アサーション)を作成・管理します — 特定の受領者に発行されたバッジです。

すべてのエンドポイントは X-Api-Key ヘッダーでの認証が必要です。認証を参照してください。

授与の作成

受領者にバッジを発行します。

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 形式の有効期限
`blockchain`	string	任意	オンチェーン検証用のブロックチェーン。対応は `matchain` のみ。Pro プランで利用可。

例

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

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

注意

月次クォータから 1 件消費します(Free: 100/月、Starter: 1,000/月、Pro: 10,000/月)。クォータは各請求期間にリセットされます。
blockchain パラメータは Pro プランのみで利用可能です。

授与の一覧

任意のフィルタとページングで授与を取得します。

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

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

レスポンスに lastEvaluatedKey があれば、さらに結果があります。次のリクエストで query パラメータとして渡すと次ページを取得できます。

授与メールの送信

受領者へ授与に関するメール通知を送ります。

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

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

授与を共有

授与を複数の受領者にメールで共有します。

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

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

PDF 証明書のダウンロード

授与用の印刷可能な A4 PDF 証明書を生成します。

GET /awards/{awardGuid}/pdf

認証は不要 — このエンドポイントは公開されており、受領者が自分の証明書をダウンロードできます。

例

bash

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

レスポンスは Content-Type: application/pdf ヘッダーのバイナリ PDF です。

授与イベントの記録

エンゲージメントイベント(閲覧、共有、ダウンロード、LinkedIn 追加)を記録します。公開授与ページがエンゲージメント統計を埋めるために使います。認証は不要です。

POST /awards/{awardGuid}/event

パラメータ

パラメータ	型	必須	説明
`kind`	string	必須	`view`、`share`、`download`、`linkedin_add` のいずれか。
`network`	string	任意	`kind=share` のとき、SNS を示す: `linkedin`、`twitter`、`facebook`、`whatsapp`、`telegram`、`email`、`copy`。

IP ごとの重複抑制: 同じ IP から同じ kind は 24 時間に 1 回カウントされます。

例

bash

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

授与統計の取得

授与の累積エンゲージメントカウンタを取得します。

GET /awards/{awardGuid}/stats

認証は不要です。

レスポンス

json

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

授与 API ​

授与の作成 ​

パラメータ ​

例 ​

レスポンス ​

注意 ​

授与の一覧 ​

クエリパラメータ ​

フィルタオブジェクト ​

例 — すべての授与を一覧 ​

例 — バッジで絞り込み ​

レスポンス ​

授与メールの送信 ​

パラメータ ​

例 ​

レスポンス ​

授与を共有 ​

パラメータ ​

例 ​

レスポンス ​

PDF 証明書のダウンロード ​

例 ​

授与イベントの記録 ​

パラメータ ​

例 ​

授与統計の取得 ​

レスポンス ​

授与 API

授与の作成

パラメータ

例

レスポンス

注意

授与の一覧

クエリパラメータ

フィルタオブジェクト

例 — すべての授与を一覧

例 — バッジで絞り込み

レスポンス

授与メールの送信

パラメータ

例

レスポンス

授与を共有

パラメータ

例

レスポンス

PDF 証明書のダウンロード

例

授与イベントの記録

パラメータ

例

授与統計の取得

レスポンス