大量注文の開始前におけるAPI経由の残高確認

キューの開始前に残高を照会する理由

最新の残高確認を行わずに注文を大量に開始すると、一部が失敗します。最初の申請は作成されますが、その後の申請で資金不足のエラーが発生します。特に、並列送信、異なるサービス、同一アカウントで動作する複数のプロセスが関与する場合、このような状況の対処は最も困難です。

開始にあたって重要なのは、入金の総額やマイページの会計上の残高ではありません。新しい注文の作成時点でサービスが引き落としを許可する金額が必要です。有効な申請に対する資金はすでに予約されている可能性がありますが、最終的な引き落としはまだ取引履歴に反映されていません。

キューの予算は、口座の総額ではなく、利用可能残高のフィールドと比較してください。

残高メソッドの応答の見方

フィールド名は各プラットフォームのドキュメントで定義されますが、使いやすい残高メソッドの契約は通常、total、available、reserved、currency、updated_at を返します。以下は、統合時の参考として使用できる構造の例です。これは各サービスの汎用的な応答ではなく、分かりやすいデータスキーマの例です。

リクエストは次のようになります。

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

応答:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

この例では、total はアカウントの全資金、available は新規注文用の資金、reserved は以前に作成された操作に対する金額です。検証は一致します。125.80 から 41.30 を引くと 84.50 になります。currency フィールドは計算単位を指定し、updated_at はデータがどれだけ新しいかを判断するのに役立ちます。

available と reserved の解析方法

available フィールドは開始の判断に使用します。キューが 80.00 で、available が 84.50 の場合、API が別途手数料を追加しない、または申請作成時に価格を再計算しない場合に限り、資金は十分です。reserved フィールドは利用可能残高に加算しません。この金額はすでに確保されています。

reserved には、processing、pending、review ステータスの注文のコストが含まれる場合があります。正確なセットはプラットフォームのルールによって異なります。キャンセル、一部実行、または手動確認後に予約が解除されることがあります。そのため、注文リストから独自に計算することは、追加の照合としてのみ可能です。

• total は入金・引き落とし履歴との照合に適しています。
• available は新しいキューの開始許可に適しています。
• reserved は有効な操作のためにすでにブロックされている資金の額を示します。
• currency は単一のアカウントでの作業でも無視できません。
• updated_at はログや古い応答の診断に役立ちます。

balance フィールドのみの応答は処理が簡単ですが、欠点があります。この資金がすぐに利用可能か、一部が他の注文のためにすでに保留されているかを判断できません。

APIドキュメントで金額の形式を確認する

例では、金額は数値 84.5 ではなく、文字列 "84.50" として渡されています。この形式は、サービスが返した正確な値を保持します。API が小数点付きの文字列を使用する場合、すぐに浮動小数点数に変換して float で比較するべきではありません。

たとえば、計算が期待される 84.50 ではなく 84.499999 になることがあります。予算の境界では、これによりキューを誤って通過させたり、逆に停止させたりする可能性があります。文字列の小数値を操作するには、固定小数部の精度をサポートする10進データ型を使用してください。

もう1つの一般的な契約は、整数の最小単位です。その場合、応答には "available_minor": 8450 と "currency": "USD" が含まれ、注文価格は "price_minor": 1250 になります。このような API 内では、通貨ルールが2桁の小数位を想定している場合、8450 は 84.50 を意味します。値を100で割るのは、ドキュメントで明示されている場合のみです。

通貨と価格形式を混在させない

キューの計算前に、残高の currency を価格メソッドまたは注文作成時の応答の通貨と比較してください。残高が1つの通貨を返し、サービスカタログが別の通貨を返す場合、数値を直接代入できません。プラットフォーム自体が提供する計算、または別途確認された換算メソッドが必要です。

自社側での事前換算は計画には便利ですが、欠点があります。サービスは引き落とし時点で異なるレート、手数料、または丸めルールを適用する可能性があります。API が残高の通貨で最終コストを返すパラメータで注文を送信するか、作成直前に価格計算を取得する方が信頼性が高いです。

価格メソッドが "price": "12.345" を返し、残高が2桁の値を保持している場合、丸めルールを確認してください。自動的に切り捨てないでください。実際の引き落としが高くなる可能性があります。キューの許可には、API が注文の最終コストと呼ぶ金額を正確に使用してください。

最初のリクエスト前にキューの予算を計算する

開始前にすべての申請を収集し、ボリューム、選択したサービス、地域、追加オプション、および別途渡される場合は手数料を考慮してコストを計算します。available をインターフェースの基本価格と比較しないでください。API では、合計は特定の注文のパラメータに依存する場合があります。

たとえば、キューに3つの注文があるとします。価格計算 API はそれらに対して、balance.currency で示されたのと同じ通貨で 18.40、27.15、31.60 を返しました。予算は 77.15 です。balance.available が 84.50 の場合、計画的な開始後は 7.35 が残ります。available が 76.90 の場合、キュー全体を開始できません。

1. 各注文の実際のパラメータに基づいて価格を取得します。
2. 形式と通貨を変更せずに最終コストを合計します。
3. 予算を最新の残高応答の available と比較します。
4. 残高が十分な場合、金額をローカル開始予約として記録します。
5. 各申請の作成後、確認されたコスト分だけローカル予約を減らします。

余裕は追加の引き落とし時の拒否リスクを減らしますが、欠点があります。キューが完全に通過できたとしても、利用可能な資金の一部が未使用のまま残ります。

送信直前に再確認する

キャンペーン準備時に取得した残高はすぐに古くなります。計算と開始の間の時間に、別のオペレーター、自動化、または有効な注文が available と reserved を変更する可能性があります。再リクエストは、キュー形成後と最初の申請の直前に必要です。

実用的なスキームは2段階です。まず価格を取得して予算を見積もり、次に balance を再度リクエストします。available の値が減少し、計算額を下回った場合、キュー全体を送信しません。最終確認と開始の間に、同じアカウントから他の引き落としを実行しないでください。

開始全体で1回のリクエストは API の負荷を減らしますが、欠点は、長いキューの処理中に利用可能残高が変わる可能性があることです。

資金不足時のキューの開始方法

available が予算より少ない場合、一部が通過することを期待してすべてのリクエストを送信しないでください。キューを、利用可能な制限に収まるコストのバッチに分割します。残高 76.90 の例では、最初の2つの注文を 45.55 で送信し、その後停止できます。3番目の 31.60 は再確認が必要です。

バッチ処理時の申請順序を明示的に設定します。優先注文を最初に送信するか、コストが近いバッチを形成できます。各オプションには欠点があります。優先順序は重要度の低い項目を遅らせ、価格による並べ替えはキャンペーンの元の計画を乱す可能性があります。

• 現在の available を超えない金額のバッチを形成します。
• バッチから注文を作成し、その識別子を保存します。
• 応答を待つか、タイムアウト後に操作ステータスを確認します。
• API の制限やサービスのルールで必要な場合は一時停止します。
• 次のバッチの前に balance を再リクエストします。

各バッチ後は、以前の残高からのローカル控除だけでなく、新しい API 応答に基づいてください。 ローカル計算は制御に役立ちますが、返金、外部引き落とし、予約の再計算は見えません。

並列送信時の予算を保護する

順次処理では、注文確認後にローカル制限を減らすだけで十分です。並列モデルでは、2つのワーカーが同時に available 84.50 を確認し、それぞれ 60.00 の支出を計画する可能性があります。両方の決定は個別には許容可能に見えますが、合わせると利用可能残高を超えます。

保護には、共有のローカル予約カウンター、またはアトミックにアクセスされるキューが必要です。送信前に、ワーカーはこのカウンターで注文金額を確保しようとします。空き制限が不足している場合、申請は残高の再確認を待ちます。

• 順次キューは制御が簡単ですが、開始が遅くなります。
• 並列送信は開始時間を短縮しますが、共有予算のロックが必要です。
• ローカル予約は競合を減らしますが、ワーカー障害後にスタックする可能性があります。
• API側の予約はより信頼性が高いですが、すべてのプラットフォームで利用可能ではありません。

応答を受け取る前にプロセスが終了した場合、ローカル予約をすぐに消費済みまたは空きとして扱うことはできません。まず、外部識別子または操作検索メソッドで注文が作成されたかどうかを確認してください。

API予約が提供されている場合は使用する

一部の API では、一連の操作の予約を作成するか、2段階で注文を処理できます。計算、金額のブロック、確認。このスキームでは、確認と引き落としの間の、別のプロセスがアカウントの資金を消費できるウィンドウが小さくなります。

そのようなメソッドがある場合、予約識別子、その金額、通貨、有効期限、ステータスを保存します。次に、API 契約が要求する場合、注文作成時にこの識別子を渡します。キューの完了後、未使用部分とブロック解除の事実を照合します。

API予約はすべての問題を解決しません。有効期限が短い、手数料をカバーしない、または確認エラー後に解除される可能性があります。ローカル予約は実装が簡単ですが、欠点は、アプリケーション外で作成された支出から保護しないことです。

残高エラーとゼロ残高を区別する

エラーコード付きの応答、タイムアウト、またはレート制限は、available がゼロであることを意味しません。大規模な開始が依存する場合、最後に知られた値を自動的に代入しないでください。最新の残高を取得できない場合、キューを一時停止する必要があります。

注文作成時の拒否を別途処理します。資金不足に関連する場合がありますが、無効なサービス識別子、許容できないボリューム、チャネル制限、または同一操作の重複にも関連する可能性があります。エラーコードとテキストを申請の外部識別子とともに保存します。

• 認証エラーの場合、アクセスを更新してからリクエストを再試行します。
• レート制限の場合、API ルールに従って一時停止します。
• 作成タイムアウトの場合、まず操作が実際に出現したかどうかを確認します。
• 資金不足エラーの場合、バッチを停止し、balance を再リクエストします。

タイムアウト後に重複を作成しない

タイムアウトは、クライアントが応答を受け取らなかったことを意味し、サーバーがリクエストを処理しなかったことを意味しません。確認せずに再送信すると、2番目の注文が作成され、資金が再び確保される可能性があります。特に、自動再試行が複数回設定されているキューでは危険です。

API が client_order_id、external_id、または idempotency_key フィールドをサポートしている場合、一意の外部注文識別子を渡します。リクエスト送信前に保存します。タイムアウト後、この値で操作を検索するか、以前に取得した識別子でステータスをリクエストします。

確認なしの再試行は高速ですが、欠点は直接です。注文の重複、二重予約、予算計算と実際の引き落としの不一致が発生する可能性があります。

開始ログに保存するもの

ログは大量操作の進行を復元し、特定のバッチが停止した理由を説明するのに役立ちます。各開始について、2回の確認時刻、total、available、reserved、currency、計算された予算、ローカル予約のサイズ、申請の外部識別子のリストを保存します。

各作成試行について、コスト、応答コード、操作の技術識別子、最終ステータスを記録します。シークレットはログに含まれません。認証トークン、API キー、完全なリクエストヘッダー、個人データは、記録前にマスクまたは除外する必要があります。

完全なログはデバッグに便利ですが、欠点があります。フィルタリングなしでは、アクセスデータや顧客情報がストレージに入る可能性があります。

小規模なキューでスキームをテストする

大規模な開始前に短いシナリオを実行します。balance を取得し、最終価格をリクエストし、制限されたバッチを作成し、再度 balance をリクエストし、available と reserved の予想される変化を実際の応答と比較します。これにより、サービスが金額を予約する時と最終的に引き落とす時を確認できます。

テストバッチは高負荷時の同一の動作を保証しません。制限、並列プロセス、または特定のサービスの制約が発生する可能性があります。そのため、大量キューでは、開始をバッチに分割し、それらの間で利用可能残高を確認し、各拒否を個別に処理し続けてください。