> ## 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.

# カード単位の購入数量制限 API

> 署名付きの transactionlimit create / update / inquiry エンドポイントを使用して、1 枚のカードが購入できる商品または商品カテゴリの数量に上限を設ける方法：リクエストフィールド、相互排他の 2 つの制限グループ、冪等性、有効期間、ルールに該当した際に購入者に表示される内容を説明します。

> [!WARNING]
>
> この機能は、エンドポイントが応答する前に、貴社のアカウントで有効化されている必要があります。呼び出しが権限エラーで返ってきた場合は、リクエストをデバッグするのではなく、Waffo の連携担当者にお問い合わせください。

デジタルグッズ、ゲーム内通貨、イベントチケットなど、転売業者がまとめ買いしがちなものを販売している場合、商品ごと、または商品カテゴリごとに、**1 つの決済手段（支払い手段）が購入できる数量**に上限を設けることができます。Waffo は決済時にこの上限を強制し、超過した場合は決済を拒否します。

このページでは、貴社のシステムからこれらのルールを管理できる 3 つの署名付きエンドポイントについて説明します。金額の上限に関するページではありません。決済手段ごとの最小/最大注文金額、およびアカウント単位の 1 取引あたり・1 日あたりの金額制限については
[制限、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement)
をご覧ください。署名、キー、ヘッダーは他のすべての API とまったく同じように動作します。
[認証と署名](/docs/ja/support/auth-signature-faq)
をご覧ください。

## 具体的に何を制限でき、ルールに該当するとどうなりますか？

以下のいずれかに対して、**決済手段あたりの最大数量**を登録します：

* 特定の 1 商品 — 商品識別子と、その商品に許可する最大数量を指定する
* 1 つの商品カテゴリ — カテゴリと、そのカテゴリに含まれるすべての商品を合わせて許可する最大数量を指定する

以降、注文を作成する際に商品情報と購入数量を渡します。その注文によって当該決済手段が登録済みの最大数量を超えることになる場合、決済は**拒否**され、購入者は決済を完了できません。数量を減らして注文が黙って成功することはなく、部分的な受け付けもありません。

設計上考慮すべき 2 つの結果：

* このルールは**ハードな拒否**であり、レビューキューではありません。より穏やかな結果（警告、手動レビュー、顧客ごとの許容量）を望む場合は、注文作成を呼び出す前に貴社側でそれを構築する必要があります。
* 拒否された試行は、注文に対する通常のリスク拒否です。購入者には中立的なメッセージを表示し、同じ注文を自動的にリトライしないでください。リトライしても同じルールに該当します。

## どのエンドポイントがあり、それぞれ何ができますか？

| エンドポイント | 機能 |
| - | - |
| `POST /api/v1/risk/transactionlimit/create` | 新しいルールを登録する |
| `POST /api/v1/risk/transactionlimit/update` | 既存のルールを変更する、または終了する |
| `POST /api/v1/risk/transactionlimit/inquiry` | ルールを読み取る |

3 つとも同じホスト上の署名付きエンドポイントで、注文作成と同じヘッダー、同じ署名アルゴリズムを使用します。これらは API キーの **payin** スコープに属するため、出金や送金のみのために発行されたキーでは呼び出せません。

## create では何を送信しますか？

| フィールド | 備考 |
| - | - |
| `merchantInfo.merchantId` | 必須。API キーが発行された加盟店 ID と同じでなければなりません。次の質問をご覧ください。 |
| `merchantInfo.subMerchantId` | オプション。指定する場合、その加盟店 ID に属するサブ加盟店でなければなりません。 |
| `merchantRequestId` | 必須。このルールに対する貴社独自の参照であり、冪等キーです。 |
| `goodsInfoLimitConfig.goodsId` + `maxGoodsQuantity` | 商品レベルのグループ。両方を一緒に送信します。 |
| `goodsInfoLimitConfig.goodsCategory` + `maxCategoryQuantity` | カテゴリレベルのグループ。両方を一緒に送信します。 |
| `startTime` | 必須。ルールの適用開始時刻。ISO 8601 形式（例：`2026-09-01T03:00:00.000Z`）。 |
| `endTime` | ルールの適用終了時刻。同じ形式。 |
| `extendInfo` | オプションのパススルー。JSON 文字列。 |

どちらの最大数量値も **1 以上**でなければなりません。最大数量をゼロにしても商品を完全にブロックすることはできません。商品を購入不可にしたい場合は、その商品を提供しないでください。

## 同じリクエストで商品制限とカテゴリ制限を同時に設定できますか？

いいえ。2 つのグループは**リクエストごとに相互排他**です：

* `goodsId` と `maxGoodsQuantity` は一緒に指定する必要があります。
* `goodsCategory` と `maxCategoryQuantity` は一緒に指定する必要があります。
* 1 回の create 呼び出しには、この 2 つのグループのうち**1 つ**しか含められません。

商品ごとの上限とカテゴリごとの上限の両方が必要な場合は、2 つのルールを作成してください。

## 加盟店 ID に関するパラメータエラーが出るのはなぜですか？

ボディ内の `merchantId` が、API キーの発行対象である加盟店 ID と一致しなかったためです。3 つのエンドポイントはすべて、他の処理を行う前に両者が一致することを検証し、一致しない場合は `A0003` **Parameter validation failed** に詳細 `mid in params is inconsistent with apiKey` を付けて呼び出しを拒否します。

同じチェックは `subMerchantId` にも適用されます。送信する場合、それが存在し、リクエスト内の加盟店 ID に属していなければなりません。そうでない場合、詳細 `subMerchantId is invalid or does not belong to the provided merchantId` を付けた `A0003` が返されます。

これはここで最も多い連携ミスであり、ほぼ常に次の 2 つのいずれかです：別アカウントのキー（本番環境に対するサンドボックスキー、またはサブアカウントのキー）、あるいはコピーしたサンプルに残っていたハードコードされた加盟店 ID です。

## 何が返され、`ruleStatus` は何を意味しますか？

create と update はどちらも、識別子とルールのステータスを返します：

| フィールド | 備考 |
| - | - |
| `ruleId` | Waffo によるルールの識別子。保存してください。これが安定したハンドルです。 |
| `merchantRequestId` | エコーバックされるため、応答をリクエストに対応付けられます。 |
| `ruleStatus` | `ACTIVE` — ルールが存在し、有効期間内に評価されます。`TERMINATED` — ルールは適用されなくなりました。 |

`ACTIVE` はルール自身のライフサイクルを表すものであり、現在有効かどうかを表すものではないことに注意してください。将来の `startTime` を持つルールは `ACTIVE` であり、単にまだ開始していないだけです。

## create 呼び出しがタイムアウトした場合、冪等性はどのように機能しますか？

`merchantRequestId` が冪等キーです。同じ `merchantRequestId` で同一のリクエストを再送すると、2 つ目のルールではなく既存のルールが返されます。タイムアウトからはルールが作成されたかどうか判別できないため、これはタイムアウト後に望ましい動作です。

そこから 2 つのルールが導かれます：

* **`merchantRequestId` は試行ごとではなく、意図するルールごとに 1 つ生成してください。** リトライ時に新しいものを生成すると、ルールが 2 つできてしまいます。
* **異なるルールに `merchantRequestId` を再利用しないでください。** 異なる内容で冪等キーを再利用した場合に返されるのが `A0011` **Idempotent param mismatch error** です。

## ルールを変更または停止するにはどうすればよいですか？

`update` を呼び出し、`merchantRequestId` **または** `ruleId` のいずれかでルールを特定します。どちらか一方が必須で、曖昧さがないため `ruleId` の方が安全な選択です。

update では制限フィールドはオプションで、create と同じペアリングルールに従います。`goodsId` を送るときは必ず `maxGoodsQuantity` を、`goodsCategory` を送るときは必ず `maxCategoryQuantity` を送ってください。`startTime` と `endTime` を移動することもできます。

ルールを停止するには、`ruleStatus` を `TERMINATED` に設定します。削除はありません。終了したルールは `inquiry` で引き続き読み取ることができ、過去の拒否を説明する必要がある場合に役立ちます。

## ルールを読み取るにはどうすればよいですか？

`merchantInfo` に加えて `merchantRequestId` **または** `ruleId` のいずれかを指定して `inquiry` を呼び出します。応答は Waffo が保持しているとおりのルール（識別子、`ruleStatus`、制限設定、有効期間）を返します。

次の 3 つの用途に使用してください：

* create か update かを決める前の、**タイムアウト後の照合**。
* 貴社側の設定コピーを信頼するのではなく、販売前に**実際に有効な内容を検証**する。
* 有効だったルールを示して、サポートチームに**拒否を説明**する。

## 注文作成について何か変更する必要がありますか？

はい。ルールは、貴社が実際に送信した情報に対してのみ機能します。ルールの登録だけでは何も起こりません。注文作成時に、ルールが登録されている商品識別子および/または商品カテゴリを、購入数量とともに渡す必要があります。商品情報を持たない注文は、数量ルールと照合できません。

実務上の 2 つの注意点：

* **両側で同じ識別子を使用してください。** `goodsId` として登録した値は、注文作成時に送信する値と 1 文字ずつ一致していなければなりません。大文字小文字の不一致や、別の内部 SKU 体系が、ルールが「機能しない」よくある原因です。
* **カテゴリルールには注文上のカテゴリが必要です。** 現在のカタログにカテゴリの概念がない場合は、商品ごとのルールから始める方が手軽です。

商品フィールドのフィールドレベルの詳細は
[注文作成フィールドガイド](/docs/ja/support/order-create-field-guide)
にあります。

## すべてのルールを 1 回の呼び出しで一覧取得できますか？

いいえ。`inquiry` は識別子（`ruleId` または `merchantRequestId`）による検索であり、登録したすべてのルールのページ付きリストではありません。そのため、作成したルールの台帳を貴社側で保持し、対象の商品またはカテゴリの横に `ruleId` を保存してください。

その台帳が、リリース前に監査の基準となるものです。設定ストアと Waffo が一致していると仮定するのではなく、各ルールを `inquiry` で読み取って比較してください。

## 変更はどのくらいの速さで有効になりますか？

ルールはそれ自身の有効期間に対して評価されるため：

* 過去の `startTime` で作成されたルールは、次の注文から有効です。
* 将来の `startTime` で作成されたルールはその時刻まで何もしません。これが、リリースやフラッシュセールに先立って上限を準備しておくためのきれいな方法です。
* ルールを終了すると適用が停止します。すでに成功した決済は影響を受けません。

見落とされがちな結果が 1 つあります：**ルールを有効化する前に作成した注文でも、購入者がその後に支払う場合はルールに対して評価されます。** スクリーニングは注文作成時ではなく、実際に決済が試行される時点で行われるため、上限を有効化した時点でチェックアウトページに留まっている注文は、決済時に拒否されます。新しいルールの影響を受けないのは、すでに成功した決済のみです。

セール開始のちょうどその秒にルールが開始するようスケジュールしないでください。十分余裕をもって前に有効化し、`inquiry` で期待どおりに読み取れることを確認してください。

## ルールが発動したとき、購入者の決済にはどのエラーが返されますか？

ルール固有のコードではなく、**リスク拒否**です。決済は他のリスク判定とまったく同様に、`D0001`（リスク拒否）または `D0002`（リスク取引限度額）、HTTP `406` で失敗します。「加盟店自身のルールがこれを拒否した」ことを示すコードはありません。

そこから 2 つのことが導かれます：

* **何を制限したかの記録を貴社側で保持してください。** 注文照会および決済通知では、失敗は汎用的な拒否カテゴリの下で報告されるため、事後に拒否を貴社自身のルールに帰属させることはできません。
* **購入者に有用な情報を伝えてください。** コードは貴社が設定した上限と他の拒否を区別しないため、インターフェース上の文言はレスポンスではなく、貴社自身のルールに関する知識に基づく必要があります。

2 つのコードが各画面でどう動作するかについては、[リスク拒否と 3D セキュア](/docs/ja/support/risk-declines-and-3ds-faq)をご覧ください。

## 明示的に処理すべきエラーはどれですか？

分岐する価値のあるコードは以下のとおりです。一般的なエラーファミリーは
[一般的なエラーのトラブルシューティング](/docs/ja/support/errors-troubleshooting-guide)
に記載されています。

| コード | 意味 | 対処 |
| - | - | - |
| `A0001` | Invalid API secret key | キーが誤っているか取り消されている、または環境が違います。 |
| `A0002` | Invalid signature | 署名の問題です。署名 FAQ をご覧ください。 |
| `A0003` | Parameter validation failed | 詳細テキストにフィールド名が示されます。加盟店 ID の不一致、サブ加盟店チェック、フィールドのペアリングルールを含みます。 |
| `A0004` | Permission denied | キーがこの呼び出しのスコープを持たないか、機能がアカウントで有効化されていません。 |
| `A0011` | Idempotent param mismatch | 異なる内容で `merchantRequestId` を再利用しました。 |
| `C0001` | System error | 同じ `merchantRequestId` でリトライしてください。冪等性が守ってくれます。 |

**決済**側では、登録済みルールに該当した注文はパラメータエラーではなく、リスク拒否として拒否されます。その注文については最終結果として扱ってください。

## ルールはサブ加盟店に適用されますか？

ルールはリクエスト内の加盟店 ID に対して登録され、オプションで 1 つのサブ加盟店に絞り込むことができます。複数のサブ加盟店を運営し、すべてに同じ上限を適用したい場合は、サブ加盟店ごとにルールを登録してください。1 つのサブ加盟店にスコープされたルールは他のサブ加盟店をカバーせず、エンドポイントは指定したサブ加盟店が本当に貴社に属していることを検証します。

サブ加盟店モデルに初めて触れる場合は、
[マルチブランドとサブ加盟店の構成](/docs/ja/support/multi-brand-and-sub-merchant-faq)
から始めてください。

## すでにある金額制限とはどう違うのですか？

これらは無関係なチェックであり、失敗の仕方も異なります。拒否を診断する際にはこの点が重要です：

| チェック | 測定対象 | 設定場所 |
| - | - | - |
| カード単位の購入数量制限（このページ） | 1 つの決済手段で購入された商品またはカテゴリの**数量** | 貴社が、これらのエンドポイントを通じて |
| 決済手段の金額範囲 | その決済手段と通貨の最小/最大に対する注文**金額** | 契約設定 |
| アカウントの 1 取引あたり・1 日あたりの制限 | 注文通貨ごとの注文金額、および当日の累計金額 | アカウント設定 |

数量ルールは 1 件の非常に大きな注文を止めることはできず、金額制限は 100 件の小さな注文を止めることはできません。まとめ買いが問題なら、数量ルールが必要です。

## 次はどこを見ればよいですか？

* [注文作成フィールドガイド](/docs/ja/support/order-create-field-guide) — 注文作成時に渡す商品フィールド。
* [制限、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement)
  — 金額ベースの上限と、どのコードが何を意味するか。
* [決済結果の確認](/docs/ja/support/payment-results-faq) — 拒否された決済がどのように報告されるか。

拒否が貴社自身のルールによるものかまだ不明ですか？注文 ID と `ruleId` を添えて[サポートにお問い合わせ](mailto:support@waffo.com)ください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.