> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# モード B：ポイントコード取得 API

> ユーザーが支払いを完了した後、Waffo Point Topup がサプライヤーのポイントコード取得 API をリアルタイムで呼び出します。リクエスト・レスポンス項目、冪等性の要件、サンプル。

モード B は、API 機能を備えたポイント在庫システムを有するサプライヤー向けです。ユーザーが支払いを完了した後、Waffo Point Topup がサプライヤーの API を呼び出してリアルタイムでポイントコードを取得します。

<CardGroup cols={2}>
  <Card title="メリット" icon="circle-check">
    * リアルタイムポイントコード取得
    * 手動在庫管理不要
    * 自動在庫同期
  </Card>

  <Card title="ユースケース" icon="users">
    * デジタルポイント生成システムを有するゲームパブリッシャー
    * 既存 API を有するポイントコードディストリビューター
  </Card>
</CardGroup>

## 連携フロー

<Frame>
  <img src="https://mintcdn.com/waffo-docs/hUiobY-hbNbq3QYe/images/developer-docs/point-topup/mode-b-flow.png?fit=max&auto=format&n=hUiobY-hbNbq3QYe&q=85&s=f9f91095f4a7831e5eb34c14ed8d31be" alt="モード B のポイントコード取得フロー：決済完了後に Waffo がサプライヤーのエンドポイントを呼び出してコードを取得し、ユーザーにメール送信" width="2653" height="1584" data-path="images/developer-docs/point-topup/mode-b-flow.png" />
</Frame>

## API 一覧

| No. | API 名     | 説明              | 提供元    | 連携要否         |
| --- | --------- | --------------- | ------ | ------------ |
| 1   | ポイントコード取得 | リアルタイムポイントコード取得 | サプライヤー | 任意連携（サンプル仕様） |

<Warning>
  本ページの API 仕様は**サンプル／参考用のみ**です。すでにポイントコード取得用の API を有する場合、既存の API ドキュメントを Waffo Point Topup に提供すれば統合が可能です。Waffo Point Topup はサプライヤーの既存 API インターフェースに対応するため、本ページに合わせて作り直す必要はありません。
</Warning>

## ユーザーリダイレクト

自社ウェブサイトから Waffo Point Topup へユーザーをリダイレクトしたい場合、モード C の [URL 署名方式](/docs/ja/developer-docs/point-topup/mode-c-direct-fulfillment#url-署名とリダイレクト)を利用できます。あるいは、署名なしで直接リンクを提供するだけでも構いません。

```text theme={null}
https://{supplier}.waffoplay.com/{site_code}/
```

## ポイントコード取得エンドポイント

ユーザーが支払いを完了した後、Waffo Point Topup によって呼び出され、サプライヤーからポイントコードを取得します。

| 項目     | 値                                                                                            |
| ------ | -------------------------------------------------------------------------------------------- |
| Method | `POST`                                                                                       |
| Path   | サプライヤーが定義                                                                                    |
| 認証     | 共通 API 署名（SHA256WithRSA）。[API 共通仕様](/docs/ja/developer-docs/point-topup/api-common#api-セキュリティ)を参照 |

<Warning>
  **冪等性の要件：** サプライヤーは `distributorOrderId` + `distributorId` を使用して冪等性をサポートする必要があります。同じリクエストが複数回受信された場合、在庫を再度減算せずに同じポイントコードを返してください。
</Warning>

### リクエスト

| フィールド名               | 説明                                                     | 型           | 必須 |
| -------------------- | ------------------------------------------------------ | ----------- | -- |
| `distributorId`      | サプライヤーが Waffo Point Topup に割り当てたディストリビューター ID          | String(64)  | 必須 |
| `distributorOrderId` | Waffo Point Topup の注文 ID。`distributorId` と併せて冪等キーとして使用 | String(64)  | 必須 |
| `skuId`              | SKU 識別子                                                | String(128) | 必須 |
| `quantity`           | 取得するポイント数（通常は 1）                                       | Integer     | 必須 |
| `faceValue`          | 額面金額（動的価値の商品向け）                                        | String(32)  | 任意 |
| `requestedAt`        | Waffo Point Topup 側リクエスト時間                             | String(32)  | 必須 |

### レスポンス

| フィールド名               |              | 説明                                        | 型           | 必須 |
| -------------------- | ------------ | ----------------------------------------- | ----------- | -- |
| `distributorOrderId` |              | Waffo Point Topup の注文 ID                  | String(64)  | 必須 |
| `status`             |              | 注文ステータス：`SUCCESS` ポイント取得成功、`FAILURE` 取得失敗 | String(24)  | 必須 |
| `pointList`          |              | ポイントコードのリスト。`status` が `SUCCESS` の場合のみ返却  | Array       | 任意 |
|                      | `pointCode`  | ポイントコード                                   | String(128) | 必須 |
|                      | `expiryDate` | 有効期限                                      | String(32)  | 任意 |
|                      | `faceValue`  | 額面金額                                      | String(32)  | 任意 |
| `failureCode`        |              | 失敗コード（`status` が `FAILURE` の場合）           | String(24)  | 任意 |
| `failureReason`      |              | 失敗理由                                      | String(128) | 任意 |

### サンプル

<CodeGroup>
  ```json リクエスト theme={null}
  {
    "distributorId": "WAFFO_POINT_TOPUP_001",
    "distributorOrderId": "WP202501050001",
    "skuId": "SUPPLIER_POINT_001",
    "quantity": 1,
    "faceValue": "1000",
    "requestedAt": "2025-01-05T10:30:00.000Z"
  }
  ```

  ```json レスポンス（成功） theme={null}
  {
    "code": "0",
    "msg": "success",
    "data": {
      "distributorOrderId": "WP202501050001",
      "status": "SUCCESS",
      "pointList": [
        {
          "pointCode": "ABCD-1234-EFGH-5678",
          "expiryDate": "2026-12-31",
          "faceValue": "1000"
        }
      ]
    }
  }
  ```

  ```json レスポンス（失敗） theme={null}
  {
    "code": "0",
    "msg": "success",
    "data": {
      "distributorOrderId": "WP202501050001",
      "status": "FAILURE",
      "failureCode": "INSUFFICIENT_INVENTORY",
      "failureReason": "No available points in inventory"
    }
  }
  ```
</CodeGroup>

<Note>
  `status` が `FAILURE` の場合は業務上の失敗であり、HTTP ステータスコードと外側の `code` は成功を返します。システムレベルのエラーは[エラーコード](/docs/ja/developer-docs/point-topup/api-common#エラーコード)に従って返してください。
</Note>

## 次のステップ

<CardGroup cols={2}>
  <Card title="API 共通仕様" icon="shield-check" href="/docs/ja/developer-docs/point-topup/api-common">
    メッセージ構造、RSA 署名と検証、エラーコード、鍵の生成。
  </Card>

  <Card title="モード C：即時履行 API" icon="zap" href="/docs/ja/developer-docs/point-topup/mode-c-direct-fulfillment">
    ポイントコードを発行せずユーザーアカウントを直接チャージする場合は、モード C を参照してください。
  </Card>
</CardGroup>