API注文の完了通知を設定する方法

どのイベントを注文の完了とみなすか

まず、APIでどのステータスが注文の実際の完了を意味するかを確定してください。プロバイダーによって、完了、配信済み、キャンセル、拒否、返金、一部完了などが該当します。自動化を「成功」という言葉だけに結び付けないでください。注文は複数の中間状態を経てから、上限、審査、キャンセルによって停止することがあります。

処理すべきは肯定的な結果だけではありません。サービスがエラー、キャンセル、返金、一部完了の通知を送信する場合も、それを内部システムに記録する必要があります。そうしないと、パネル、CRM、ボット内で注文が待機状態のまま残り、実際にはそれ以上の実行が行われなくなります。

ステータスの対応表を作成する

APIのステータスを処理せずにインターフェースに渡さないでください。プロバイダーの名称やロジックは変更される可能性があり、同じ内部ステータスが複数の外部ステータスを統合することもあります。元の値は別に保存してください。エラーの調査やドキュメントとの照合に役立ちます。

• pending、created、queued — 新規または処理待ちの注文。
• processing、in_progress、running — 注文を実行中。
• completed、delivered、success — 完了した注文。
• partial、partially_completed — 一部完了した注文。
• cancelled、rejected、failed — キャンセルまたはエラーで終了した注文。
• refunded、returned — 返金または調整が必要な注文。
• 不明なステータス — カードを自動的に変更せず、確認のために引き渡します。

上記の名称はスキーマの例として示しています。最終的な対応表は特定のAPIのステータスに基づいて作成する必要があります。手動マッピングの欠点は、APIの更新後に維持する必要があることです。新しいステータスが、そのルールが作成される前にハンドラーに到達する可能性があります。

Webhook、APIポーリング、または両方の方式を選択する

Webhookは、注文ステータスが変更されたときにサービスからあなたのURLへのリクエストです。APIポーリングは逆に動作します。あなたのシステムが一定間隔で注文情報をリクエストします。完了通知には通常、Webhookの方が便利です。なぜなら、ステータス確認メソッドへの絶え間ないリクエストなしで更新が届くからです。

• Webhookは迅速な対応に適しています：カードの更新、次のステップの開始、担当者へのメッセージ送信。
• ポーリングは、プロバイダーがコールバック通知をサポートしていない場合、またはサーバーが外部リクエストを受け付けない場合に適しています。
• 組み合わせ方式では、Webhookを主要チャネルとして使用し、ポーリングは見逃した注文や停滞した注文の検索に使用します。

ポーリングの欠点は、遅延とAPIへの余分な負荷です。Webhookの欠点は、エンドポイントを保護し、重複を考慮し、イベントの配信順序に依存しないようにする必要があることです。

イベント受信用のエンドポイントを設定する

通知には、APIサービス側からアクセス可能な公開HTTPSアドレスが必要です。統合設定では通常、ハンドラーのURL、署名シークレット、イベントリスト（ステータス変更、完了、キャンセル、エラー、一部完了）を指定します。

APIイベント専用の別ルートを確保してください。そうすることで、ログ記録の設定、アクセスの制限、リクエスト制限の設定が容易になり、サービス通信をサイトのフォームと混在させずに済みます。稼働中の注文にテスト環境のアドレスを使用しないでください。環境を更新した後も、プロバイダーは保存されたURLにイベントを送信し続けます。

起動前に、ドキュメントに従ってリクエストメソッドとボディ形式を確認してください。ほとんどの場合、JSONを含むPOSTですが、form-data、クエリパラメータ、独自のシリアライズスキーマも存在します。解析エラーはログに記録する必要があります。そうしないと、不正なペイロードとアプリケーションの障害を区別するのが難しくなります。

注文とイベントの関連を保存する

API経由で注文を作成する際は、プロバイダーが返した識別子を保存してください。内部注文番号、サービスタイプ、元のステータス、最終変更時刻、APIの元のレスポンスを安全な形式で併せて保存します。受信したWebhookは、チャネルへのリンク、サービス名、顧客名ではなく、プロバイダーのIDで照合してください。

APIが作成時に外部識別子の送信を許可している場合は、external_idやclient_referenceのようなフィールドに自分の注文番号を追加してください。これにより、ログ内の検索や紛争状況の調査が容易になります。ただし、外部番号を唯一のキーにしないでください。一部のプロバイダーはすべての通知でそれを返しません。

Webhookの不明なIDで新しい注文を作成しないでください。 不明なイベントはログに保存し、別途確認する必要があります。レコードの自動作成は、誤ったデータや偽造リクエストの処理につながる可能性があります。

わかりやすいペイロード構造を使用する

正確なフィールド名はAPIによって異なります。以下は特定のサービスの契約ではなく、内部ハンドラーを設計する際に参考にできるJSONイベントの例です。重要なのは、イベント識別子、プロバイダーの注文ID、ステータス、変更時刻、診断用データです。

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

ステータスなしで実行済み単位数を完了の指標として使用しないでください。注文は一部完了の場合があり、ペイロード内の数値は丸められたり、遅延して更新されたり、まったく送信されないこともあります。イベントの完全なボディを保存する欠点は、個人データやサービスフィールドが含まれる可能性があるため、そのようなレコードはマスクし、保存期間を制限する必要があります。

リクエストの元のボディで署名を検証する

公開されたハンドラーのURLは、APIサービス以外からもリクエストを受け取る可能性があります。プロバイダーが署名、シークレット、トークンを送信する場合は、注文を変更する前にそれらを検証してください。一般的なスキームはHMAC-SHA256です。プロバイダーはリクエストボディのバイトと共有シークレットから署名を計算し、その結果をHTTPヘッダーで送信します。

計算の原則は次のとおりです。元のリクエストボディ（たとえば変更されていないJSONバイト）と統合シークレットを取得します。次にHMAC-SHA256を計算します。16進数形式の結果がヘッダーの値と一致すれば、ボディは署名後に変更されておらず、リクエストはシークレットを知っている側から送信された可能性が高いです。

条件付きの例：HMAC_SHA256(シークレット, raw_body) = X-Signatureヘッダーの署名。ヘッダー名、アルゴリズム、結果の形式はAPIドキュメントからのみ取得してください。一部のサービスは署名文字列にタイムスタンプやイベントIDを追加します。この場合、JSONボディだけを検証することはできません。

署名検証前にJSONを変更しない

署名は、アプリケーションがすでに解析して再構築したJSONオブジェクトではなく、リクエストの元のバイトで検証します。再シリアライズすると、フィールドの順序、空白、文字のエスケープ、改行、エンコーディングが変わる可能性があります。人間にとってJSONは同じに見えますが、バイトセットが変わり、HMACは一致しなくなります。

これを避けるには、まずraw bodyをbytesまたはbufferとして取得し、メモリに保存し、署名を計算し、検証が成功した後にのみJSONを解析します。ボディにtrim、エンコーディング変換、キーのソート、フォーマットを適用しないでください。フレームワークのミドルウェアで、元のボディにアクセスする前にJSONが自動的に解析されていないか確認してください。

このスキームの欠点は、ハンドラーがミドルウェアの順序に依存するようになることです。設定を誤ると、アプリケーションは変換されたオブジェクトしか見えなくなり、正当な通知が拒否され始めます。

HMAC検証付きハンドラーの例

以下はPythonでの条件付きの例です。これは完成した統合ではなく、操作の順序を示しています。ヘッダー、アルゴリズム、署名形式、ペイロードフィールドは、プロバイダーのドキュメントの値に置き換える必要があります。

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

比較には、最初の不一致文字で処理を停止しない関数を使用してください。これにより、応答時間を通じた署名情報の漏洩リスクが軽減されます。シークレットをクライアントコードに渡したり、URLに追加したり、ログに完全に記録したりしないでください。

イベント処理を冪等にする

プロバイダーは同じイベントを複数回配信する可能性があります。理由はよくあるものです。サーバーの応答が遅かった、データ保存後に接続が切断された、エンドポイントが一時的にエラーを返した、サービスが独自のルールで再配信を開始したなどです。再送はAPIが新しい注文を作成したことを意味しません。

冪等性とは、同じイベントが結果を一度だけ変更することを意味します。 このルールを考慮しないと、重複によってクライアントにメッセージが再送されたり、マネージャーに複数のタスクが作成されたり、補償が付与されたり、再操作が開始されたりします。

最善の方法は、ペイロードのevent_idを使用することです。それを一意制約付きの別テーブルまたは処理済みイベントログに保存します。個別のIDがない場合は、安定したフィールドからキーを生成します。プロバイダーの注文ID、イベントタイプ、ステータス、変更時刻です。この方法は劣ります。不正確なタイムスタンプでは、異なるイベントが同じに見える可能性があります。

イベントとステータスを1つの操作で保存する

「イベントが処理されたか」の確認と結果の書き込みはアトミックに実行する必要があります。そうしないと、同時に到着した2つの同一リクエストが両方ともレコードの不在を確認し、アクションを2回実行します。実用的な方法は、event_idの一意インデックスとデータベーストランザクションです。

ハンドラーの条件付きの続きは次のようになります。

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

不明な注文に対して成功コードで応答する欠点は、プロバイダーが配信を再試行しない可能性があることです。そのため、不明なイベントは別途監視し、迅速に調査する必要があります。APIドキュメントがそのような場合に別の応答コードを推奨している場合は、それに従ってください。

イベントの順序違反を考慮する

Webhookは必ずしもステータス変更の時刻順に届くとは限りません。最初に完了イベントが到着し、その後で「実行中」ステータスの遅延通知が届くことがあります。最後に受信した値を単純に書き込むと、完了した注文が再びアクティブになります。

許可される遷移を定義してください。たとえば、中間ステータスは最終ステータスを上書きできず、キャンセルされた注文は別途確認なしに完了に移行されません。APIが最終ステータスの修正を許可している場合は、理由、元の値、変更元を保存してください。

ペイロードに注文の変更時刻が含まれている場合は、Webhookの受信時刻ではなく、それと比較してください。APIがそのようなマークを送信しない場合は、状態の優先度と注文取得メソッドによる照合を使用してください。優先度の欠点は、実際の順序を置き換えるものではないことです。特にプロバイダーが最終ステータスからの返金を許可している場合に当てはまります。

配信を迅速に確認し、アクションをキューに移す

プロバイダーへの応答前に長時間の操作を実行しないでください。署名検証、注文検索、イベント記録、ステータス更新は通常迅速に完了できます。メッセージ送信、CRMとの同期、レポート生成、サードパーティシステムへのリクエストは、タスクキューに渡すことをお勧めします。

実用的な順序は次のとおりです。署名を検証し、イベントとステータス変更をアトミックに保存し、成功応答を返し、その後で二次アクションを実行します。保存前に応答すると、障害時にデータが失われます。通知の長時間送信後に応答すると、プロバイダーが配信を失敗とみなし、重複を送信する可能性があります。

キューの欠点は、監視が必要な別コンポーネントが追加されることです。タスクのエラー、遅延、再実行です。ただし、マネージャーへの通知の障害が注文ステータスの受信をブロックすることはありません。

チームとクライアント向けの通知を設定する

ステータス変更後、全員に同じように通知する必要はありません。マネージャーにとって通常重要なのは、キャンセル、エラー、一部完了、長期間変更されていない注文です。クライアントには、わかりやすい結果（注文完了、キャンセル、確認が必要）で十分なことが多いです。

• 完了した注文 — マイページの更新またはクライアントへの短いメッセージ。
• 実行エラー — APIが送信した理由を添えて担当者に通知。
• 一部完了 — 調整、返金、次のアクションの確認タスク。
• 不明なステータス — ログへの記録と技術スペシャリストへのメッセージ。
• 不明な注文ID — あなたのシステムとプロバイダー間の関連の別途確認。

技術的な遷移ごとにメッセージを送信しないでください。フィードはすぐにノイズになり、重要な問題が見逃されます。内部通知には、注文番号、サービス、現在のステータス、外部ID、カードへのリンクを含める必要があります。

ログを記録し、未完了の注文を照合する

ログは、サービスがイベントを送信したか、どのようなボディが届いたか、署名がなぜ失敗したか、処理がどの段階で停止したかを理解するために必要です。受信時刻、イベントID、注文ID、イベントタイプ、署名検証結果、内部ステータス、応答コードを保存してください。シークレット、トークン、個人データはマスクしてください。

配信エラー、無効な署名、不明な注文、サポートされていないステータス、重複、状態の順序のために適用できないイベントを別途追跡してください。そのようなレコードの増加は、APIスキーマの変更、シークレットの期限切れ、ルートの障害、ハンドラーロジックのエラーを示す可能性があります。

中間ステータスの注文をAPIデータ取得メソッドで定期的に照合してください。この確認はWebhookを置き換えるものではありませんが、見逃したイベント、キューの障害、外部ステータスが正しい通知なしに変更されたケースを発見するのに役立ちます。