API経由でSMMパネルの残高自動チャージを設定する方法

自動チャージ設定前に準備するもの

自動チャージはSMMパネルの残高を決済サービスまたは内部ビリングと連携させます。サービスは残高を確認し、設定したしきい値に達したら決済を作成し、支払いの確認後にのみ資金を入金します。必要なのはパネルのAPIドキュメント、決済APIへのアクセス、テスト環境と本番環境用の個別キー、そしてすべての操作のログです。

開発前に、パネルのAPIが残高を返せるか、入金リクエストを受け付けられるか、チャージ履歴を表示できるか、外部の操作IDを受け取れるかを確認してください。パネルがAPI経由の入金に対応していない場合、自動化できるのは申請の作成やオペレーターへの通知だけです。この方式の欠点は、結局手動で入金しなければならないことです。

残高確認と決済判断を分離する

残高確認はスケジュールで別タスクとして実行するのが望ましいです。残高を取得し、しきい値と比較して、結果をチャージ処理担当に渡します。未完了の操作を確認せずにAPI応答の瞬間に決済を作成しないでください。並列タスクが同じ低い残高を認識し、複数の支払いを作成する可能性があります。

新しい決済の前に、処理担当は「作成済み」「支払い待ち」「確認中」のステータスの操作がないか確認する必要があります。そのようなレコードがあれば、照合が完了するまで新しい試行は開始されません。逐次処理の欠点は、外部APIの応答が遅い場合、複数の並列リクエストよりもチャージ開始が遅れる可能性があることです。

しきい値とチャージ金額のロジックを選ぶ

残高しきい値は、アクティブな注文、サプライヤーのキュー、決済の遅延に対する余裕を持って選びます。活動が不均一なチャネルでは、平均消費だけを基準にするのは危険です。配信後、広告開始後、大量注文後には引き落としが急増する可能性があります。別途、通知が届くものの決済が必ずしも自動で作成されないクリティカルレベルを設定します。

チャージ金額は固定または選択期間の消費から計算できます。固定金額は管理と照合が簡単です。欠点は、平穏な時期には余分な資金が残高に残り、注文が急増すると1回のチャージでは足りない可能性があることです。計算金額は柔軟ですが、異常な引き落としや返金を統計から除外する必要があります。

財務制限をしきい値とは別に設定する

しきい値は、システムがチャージプロセスを開始してよいのはいつかという問いにだけ答えます。制限は別の問いに答えます。つまり、いくらの資金を引き落とせるかということです。1回の操作の最大金額、期間ごとの総上限、入金後の許容残高を設定してください。これらのルールは支払い後ではなく、決済作成前に確認されます。

自動チャージは操作および期間ごとの上限なしに資金を引き落としてはいけません。 計算金額が許可額を超える場合、操作を手動確認に移し、通知を送るのが望ましいです。厳格な上限の欠点は、支出が急速に増えた場合、担当者が上限の引き上げを確認する前に残高が尽きる可能性があることです。

個別キーを作成しアクセスを保護する

自動チャージのスクリプトには、最小限の権限を持つ個別のAPIキーを使用してください。残高の読み取り、決済の作成、ステータスの確認、確認済み操作の入金です。ユーザー、サービス設定、注文、出金へのアクセスはこのキーには不要です。サービスがIPアドレス制限に対応している場合、連携サーバーからのアクセスのみを許可してください。

キーは環境変数または保護されたシークレットストレージに保存します。ブラウザのコード、ログ、公開リポジトリ、エラーメッセージに含めないでください。各キーには所有者と明確な交換手順が必要です。キーの頻繁なローテーションの欠点は、新しいシークレットをすべてのワークフローで更新しないとチャージが停止することです。

一意の識別子で決済を作成する

各チャージには、決済APIを呼び出す前に内部識別子を割り当てます。それをログに保存し、冪等性キーまたは外部操作番号として渡します。ネットワークタイムアウト時には、同じ識別子で同じリクエストを再試行できます。決済サービスは既に作成された操作を返すべきであり、資金を二重に引き落としてはいけません。

以下はリクエストの一般的な例です。フィールド名とアドレスは特定のプロバイダーのドキュメントの値に置き換えてください。変数PAYMENT_IDには事前に作成された一意のIDが格納され、CALLBACK_URLはWebhookハンドラーを指します。

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

決済の一意性を金額と作成時刻だけで判断しないでください。2つの同一のチャージが正当である場合もあれば、障害後の再リクエストはそうではありません。自社データベースの外部IDの欠点は、確実に保存し、操作のキャンセル後に再利用しない必要があることです。

残高を確認し操作の状態を保存する

残高リクエストは、新しいチャージの判断前と入金成功後に実行する必要があります。一般的なリクエストは次のようになります：curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY"。応答には金額だけでなく確認時刻も保存し、古いデータで判断しないようにしてください。

各操作について、内部ID、プロバイダー側の決済ID、金額、通貨、作成時刻、ステータス、API応答、エラー理由を含むレコードを保持します。適切な状態の連鎖は「作成済み」「支払い待ち」「支払い済み」「入金中」「入金済み」「キャンセル済み」「要確認」です。

パネルへの入金は、確認済みでまだ処理されていない支払いに対してのみ許可されます。 履歴なしでステータスを書き換えないでください。紛争時には、どのリクエストが送信され、なぜ操作が変更されたかが分かる必要があります。詳細なログの欠点は、機密データを含む可能性があるため、アクセスを制限する必要があることです。

Webhookを受け取り決済ステータスを照合する

支払い成功ページやユーザーのリダイレクトは入金を確認するものではありません。確認となるのは決済サービスからのWebhook、またはそのAPI経由でのステータスの再確認です。Webhookを受信したら、署名、送信時刻、決済ID、外部ID、金額、通貨を確認します。その後でのみ、操作を支払い確認済みの状態に移します。

Webhookの確認後、プロバイダーに決済の最新ステータスを問い合わせると有用です。例えば：curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY"。ステータスをログのデータと照合し、同じ内部IDでSMMパネルに入金リクエストを送信します。

再送されたWebhookが2回目の入金を作成してはいけません。処理担当は外部IDで操作を見つけ、「入金済み」ステータスを確認し、新しいアクションなしで成功応答を返します。Webhookの欠点は、処理担当が利用できなかった場合に遅延したり届かなかったりする可能性があることです。

タイムアウト、リトライ、停滞した決済を処理する

決済作成後のタイムアウト時には、別のIDで新しいリクエストを送信しないでください。まず内部識別子で操作を検索するか、同じ冪等性キーでリクエストを再試行します。プロバイダーが元のリクエストを受け付けていれば、既存の決済を返します。これにより、接続切断時の二重引き落としを防ぎます。

指定時間内にWebhookが届かない場合、バックグラウンドタスクがAPI経由で決済ステータスを問い合わせます。再確認はAPIとログに負荷をかけないよう、増加する間隔と限られた試行回数で行います。長く待機状態のままの操作は、照合なしにキャンセル済みとみなさず、手動確認に移します。

一時的なネットワークエラーやAPI利用不可の応答ではリトライが許容されます。支払い拒否、金額の誤り、Webhookの無効な署名、上限超過の場合は、リクエストを自動で繰り返すべきではありません。リトライの欠点は、状態ロジックが複雑になり、プロバイダーで大規模な障害が発生した際に余分な負荷がかかる可能性があることです。

確認済みの決済をSMMパネルに入金する

入金前に処理担当はもう一度確認します。金額が上限を超えていないか、通貨が一致しているか、操作がキャンセルされていないか、ステータスがまだ「入金済み」でないか。リクエストには金額と決済の外部識別子を渡します。パネルのAPIが冪等性キーに対応している場合、同じ内部操作IDを使用してください。

リクエストの一般的な形式：curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

パネルの応答後に残高を再度リクエストし、結果をログに保存します。決済サービスで資金が引き落とされたものの、パネルのAPIがエラーを返した場合、新しい決済を作成しないでください。操作は入金の再試行または手動照合まで「要確認」ステータスのままです。この慎重なスキームの欠点は、残高が一時的に自動でチャージされない可能性があることです。

通知、スイッチ、起動チェックを追加する

通知は異常時に必要です。残高がクリティカルレベルを下回った、決済が拒否された、Webhookが受信されない、上限を超えた、APIが利用できない、操作が手動確認を要するなどです。メッセージには内部ID、ステータス、理由を記載すれば十分です。APIキー、Webhook署名、決済情報を含めないでください。

連携を削除せずに、自動チャージの個別スイッチを残してください。プロバイダーの変更、メンテナンス、エラーの疑い、支出の急変時に必要です。スイッチの欠点は明らかです。作業後に再びオンにしないと、アクティブな注文の最中に残高が尽きる可能性があります。

自動チャージ有効化前のチェックリスト

• 未完了の操作がある間は、残高確認が決済を作成しない。
• 各決済に一意の内部IDと冪等性キーが作成される。
• 1回の操作および選択期間の上限が設定されている。
• Webhookは署名、金額、通貨、識別子で検証される。
• Webhookがない場合、API経由でステータスの再照合が開始される。
• タイムアウトが最初の決済の確認前に2回目の決済作成につながらない。
• パネルへの入金は1回だけ実行され、ログに記録される。
• テストモードで成功、拒否、Webhookの重複、API利用不可を確認済み。