APIによる注文確認時の「処理中」ステータスの処理

APIレスポンスにおけるprocessingの意味

processing、in_progress、またはそれに相当する状態は、プロバイダーが注文を処理対象として受け付けたものの、結果を確定していないことを意味します。プロモーションサービスでは、リンクの確認、キューの待機、タスクの起動、または注文された数量の段階的な配信である場合があります。

processingは正常な完了を保証するものではなく、エラーを意味するものでもありません。その後、注文はcompleted、partial、canceled、またはfailedに移行する可能性があります。プロバイダーが中間ステータスを返している間は、同じリンクと同じ数量に対して再申請を作成しないでください。

processingステータスを伴うHTTP 200は、APIの正常な応答を意味するものであり、注文の正常な完了を意味するものではありません。 これらのイベントは別々に保存し、処理する必要があります。

注文確認に必要なデータ

ポーリングには、作成時にプロバイダーが返した外部注文IDが必要です。これを内部ID、元の数量、サービスのパラメータ、リンク、作成時刻、および元のAPIレスポンスとともに保存してください。チャネル名、リンク、または数量で注文を検索するのは信頼できません。これらの値は複数の申請で一致する可能性があります。

作成後にタイムアウトが発生した場合、申請を自動的に再送信しないでください。プロバイダーがリクエストを受け付けたものの、応答が途中で失われた可能性があります。まず、ドキュメントに注文検索メソッドがあればそれを使用するか、ケースを確認のために引き渡してください。

現在のステータスのみを保存する欠点は、紛争時に注文がいつprocessingに移行したか、進捗があったか、以前にどのような応答が来ていたかを復元できないことです。

curlによるステータスリクエストの例

正確なアドレス、認証方法、フィールド名はプロバイダーのドキュメントから取得してください。以下はテンプレートです。山括弧内の値は、特定のAPIのデータに置き換える必要があります。

単一注文のGETリクエスト

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

レスポンス例：

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

completed_quantityとremainsフィールドは構造の例としてのみ示されています。プロバイダーはprogress、start_count、balance、または他の名前を使用する場合があります。GETアプローチの欠点は、一部のAPIがステータス確認をPOST経由でのみ受け付けることです。

POSTリクエストとバッチ確認の例

単一注文のステータスのPOSTリクエスト

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

APIキーをURL文字列に含めないでください。リクエストアドレスはプロキシログ、分析システム、ブラウザ履歴、技術ログに記録されます。POSTの欠点は、アドレスバーから手動で確認するのが難しいことですが、それはシークレットをURLに移す理由にはなりません。

アクティブ注文のバッチリクエスト

APIがバッチ確認をサポートしている場合、複数のIDを1つのリクエストで送信します：

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

レスポンスは配列内の要素の位置ではなく、外部IDによって内部注文と照合してください。バッチ確認の欠点：プロバイダーがすべての注文を返さない、リストサイズを制限する、または1つのIDに対してのみエラーを報告する場合があります。

processingのポーリングを設定する方法

最初のprocessing応答の後、次の確認をキューに入れます。間隔はAPIドキュメント、レート制限、サービスの性質に基づいて選択してください。ステータスが急速に変化するタスクでは、最初に頻繁な確認が許容されます。段階的なプロモーションでは、継続的な短いリクエストは通常新しい情報をもたらしません。

実用的なスキームは、同じprocessing応答の後に一時停止を増やすことです。最初の確認は開始遅延の後に行われ、その後間隔は設定された最大値まで増加します。APIが進捗または新しい更新時刻を返す場合、カウントはその変更から開始できます。

• 注文作成後、すぐに何度も連続してステータスを確認しないでください。サービスがキューに入れるのに時間がかかる場合があります。
• processingが繰り返される場合は、一定の頻度を維持するのではなく、リクエスト間の間隔を増やしてください。
• 注文が同時にAPIをポーリングしないように、タスク起動時刻に小さなランダムなずれを追加してください。
• プロバイダーがRetry-Afterまたは同様の推奨を送信する場合、それを優先的に使用してください。
• Webhookのある注文では、制御ポーリングを残してください。通知が届かない場合があります。

まれなポーリングの欠点は、実際の完了後にインターフェースが古いステータスを表示する可能性があることです。頻繁すぎるポーリングの欠点は、API制限に達し、429を受け取り、余分な負荷を生み出すリスクです。

processingの制御のために保存すべき時刻

通常の実行と停止を区別するには、現在のステータスだけでは不十分です。各アクティブ注文について、作成時刻、最初のprocessing取得、最後の成功したAPI応答、外部ステータスの最後の変更、および進捗の最後の変更を保存してください。

また、元の数量、確認された実行数量、残額、およびプロバイダーの元のステータスを保存することも有用です。APIが進捗を返さない場合、それは注文が停止していると見なす理由にはなりません。最後の応答時刻と、サービスの条件に記載されている場合は予想される処理期間に基づいて判断してください。

最大待機時間をすべてのサービスに対して単一の数値で設定することはできません。 プロバイダーが特定のサービスに対して指定する期間を、キューとデータ更新のための内部余裕を持たせて使用してください。期間が指定されていない場合は、サービスカテゴリごとに個別のルールを設定し、実際の処理履歴に基づいて見直してください。

processingが変化しない場合の対処

長期にわたるprocessingはエラーを証明するものではありません。まず、成功したAPI応答が来ていたか、completed_quantityまたはremainsが変化したか、Webhookがあったか、サービスのルールが変更されていないかを確認してください。目に見える成長がないことは、プラットフォームの統計の遅延、またはプロバイダーが最終段階でのみ進捗を更新することに関連している可能性があります。

内部の待機期間を超えた場合、注文を自動的にキャンセルしないでください。臨時のステータス確認を実行し、規定のメソッドがあれば別のメソッドでデータを要求し、通知履歴を確認してください。プロバイダーがまだprocessingを確認している場合、注文を内部状態「要確認」に移行しますが、外部ステータスは置き換えずに保存してください。

• 最後に確認された応答時刻とAPI応答全体を記録してください。
• 前回のポーリング以降に進捗が変化していないか確認してください。
• 内部しきい値に達した後、自動リクエストの頻度を下げてください。
• サポートに外部ID、リンク、サービスのパラメータ、ステータス履歴、技術エラーを提供してください。
• プロバイダーの応答または明示的な最終ステータスまで、残額を再起動しないでください。

手動確認の欠点は、注文がサポートの注意を必要とすることです。しかし、自動キャンセルや重複はより危険です。プロバイダー側で実行が継続している可能性があります。

リクエストの失敗と注文ステータスを区別する方法

ネットワークエラー、タイムアウト、HTTP 429、および5xx応答は、注文自体の状態を伝えません。それらは、新しい信頼できるステータスを取得できなかったことのみを意味します。そのような状況では、最後に確認されたステータスを残し、技術エラーを記録し、新しい確認を計画してください。

429の場合、ヘッダーが送信されていればRetry-Afterを考慮してください。一時的なネットワークエラーと5xxの場合、試行間の一時停止を増やしてください。認証、署名、またはアクセス権限のエラーの場合、頻繁なリトライを設定しないでください。キー、トークンの有効期限、IP制限、アクセス設定を確認する必要があります。

APIがHTTP 200を返したが、JSONが解析できない、または応答にorder_idとstatusがない場合、応答本文全体を保存し、確認を不正としてマークしてください。ステータスの欠如をcompleted、canceled、またはprocessingに置き換えないでください。

自動再リクエストをいつ停止するか

ポーリングは無限であってはなりません。一時的なエラーに対する技術的な再試行の数を制限し、注文がprocessingにある全期間を別途制御してください。リトライ制限を使い果たした後、確認タスクを分析キューに移行し、結果なしに毎分新しいリクエストを作成しないでください。

ステータスリクエストの繰り返しは、メソッドがデータを読み取るだけの場合、通常は安全です。作成、キャンセル、補充、再起動、返金のメソッドは、タイムアウト後に機械的に繰り返すことはできません。冪等キーまたはプロバイダーの明示的な確認がない場合、そのような繰り返しは注文を二重に変更する可能性があります。

リトライ制限の欠点は、一部の更新が手動タスクになることです。無限のリトライはより悪いです。それらは障害を隠し、制限を消費し、ログ分析を複雑にします。

processing後の最終ステータスを受け入れる方法

遅延したポーリング応答または古いWebhookによるcompletedからprocessingへの逆移行を許可しないでください。各更新時に、プロバイダーからのイベント時刻、バージョン番号があればそれ、および現在の内部状態を比較してください。

• newとpendingはprocessing、canceled、またはfailedに移行する可能性があります。
• processingはcompleted、partial、canceled、またはfailedに移行する可能性があります。
• partialを自動的にcompletedと見なす必要はありません。
• completed、canceled、failedは通常最終と見なされ、自動的な逆戻りをブロックします。
• 不明なステータスまたは無効な移行は別途確認が必要です。

厳格な移行テーブルにも欠点があります。プロバイダーが正しい新しい状態を追加する可能性があります。したがって、元のステータスを保存し、内部分類で上書きしないでください。

partialと注文残額の処理方法

Partialは、元の数量の一部のみが確認されたことを意味します。API応答には、実際に実行された数量、残額、理由、および補償に関するデータが含まれる場合があります。これらの値は別々に保存してください。注文の元の数量を実行数量で置き換えることはできません。

最終応答の例は次のようになります：

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

まず、APIが正確に何を確認しているかを判断してください。返金がすでに処理された、返金が計画されているだけ、残額がキャンセルされた、またはサポートへの連絡が必要です。返金に関するフィールドがない場合、残額が自動的に補償されたと見なさないでください。

未実行部分を別の決定なしに再起動しないでください。プロバイダーがまだ計算を完了している可能性があり、プラットフォームの統計が遅延して更新される可能性があり、再申請が重複したプロモーションを作成する可能性があります。確認を待つことの欠点は、残額が即座に閉じられないことですが、余分な注文は発生しません。

Webhookは制御確認を置き換えない

Webhookを使用すると、次のポーリングを待たずにイベント直後に注文カードを更新できます。ハンドラーで外部IDによって注文を検索し、署名またはシークレットを確認し、イベントIDを保存し、許容性を確認した後にのみ移行を適用してください。

Webhookの再配信は安全でなければなりません。同じイベントを新しい変更と見なすことはできません。イベントは順不同で到着する可能性があるため、遅延したprocessingのみに基づいて最終注文を戻さないでください。

安定したWebhookでも制御ポーリングが必要です。Webhookの欠点は、より複雑な設定です。利用可能なハンドラー、偽造リクエストからの保護、重複排除、およびイベントログが必要です。

processingと停止時にクライアントに表示する内容

インターフェースに技術的なJSON全体を表示する必要はありません。processingには「注文処理中」の状態で十分です。APIが信頼できる進捗を送信した場合、確認された数量を元の数量とは別に表示し、最終結果として提示しないでください。

内部制御期間を超えた注文には、「実行を確認中」のような明確な状態を使用してください。プロバイダーの応答で確認されるまで、キャンセル、返金、または完全な完了を通知しないでください。

通知は、注文の受け入れ、最終実行、partial、キャンセル、エラー、および確認の必要性に役立ちます。各ポーリング後のメッセージはノイズを生み出し、クライアントが申請の実際の状態を理解するのを助けません。

処理ログに必要な記録

応答履歴は、停止したprocessing、失われたWebhook、部分実行に関する紛争、およびインターフェースとAPIの間の不一致を分析するのに役立ちます。各呼び出しについて、外部ID、更新ソース、リクエストと応答の時刻、HTTPコード、元のステータス、正規化されたステータス、進捗、残額、および技術エラーテキストを保存してください。

通常のログにAPIキー、トークン、署名、その他のシークレットを記録しないでください。生の応答へのアクセスを制限してください。サポートインターフェースに含まれるべきでないデータが含まれている可能性があります。

起動前に、繰り返しprocessing、進捗なし、タイムアウト、429、5xxエラー、不正なJSON、遅延Webhook、重複Webhook、partial、canceled、不明なステータスのシナリオを確認してください。テストモードは統合構造に役立ちますが、その欠点は、実際のAPIの実際のキューと遅延を再現できない場合があることです。