外部連携は失敗する前提で設計する｜再送・重複防止・監視の実務ポイント

外部連携（API、Webhook、バッチ連携、CSV連携）は、必ず失敗します。
ネットワーク断、相手側障害、タイムアウト、仕様変更、想定外のデータ…。
失敗しない設計は不可能なので、現実的には「失敗しても戻れる」「重複しても壊れない」「止まっていることが分かる」を作るのが勝ち筋です。
本記事では、外部連携を運用で詰まらせないための設計要点を整理します。

1. 失敗の種類を分ける（全部リトライは危険）

失敗は大きく分けて次の3種類です。種類を分けないと、無限リトライや二重反映が起きます。

• 一時的失敗：タイムアウト、瞬断、相手の一時的過負荷（リトライ対象）
• 恒久的失敗：認証NG、必須項目不足、仕様不一致（リトライしても治らない）
• 部分成功：相手には届いたが自分側の保存が失敗、またはその逆

恒久的失敗は、データの妥当性とエラー表示の問題です。
入力の厳密さは 即時バリデーション や、 文言は エラーメッセージ設計 の発想で「直し方が分かる」形に寄せます。

2. 冪等性（重複防止）は“連携の生命線”

Webhookや再送がある連携では、同じ通知が複数回届くのが普通です。
重複しても壊れないように、以下のいずれか（または併用）で守ります。

• 外部IDで一意：相手のイベントIDや注文IDで「既に処理済」を判定
• ハッシュで一意：内容を要約したハッシュで同一判定
• 状態遷移で一意：既に確定済なら同じ確定通知は無視（運用ルール）

ステータス管理に落とすなら、ステータス設計の実例 の考え方で、
「同じイベントが2回来たときに、現場の行動が変わるか？」で分岐を決めると、無駄な状態が増えません。

3. 再送（リトライ）は“回数”より“出口”が重要

リトライは入れるだけなら簡単ですが、運用が無いと永遠に詰まります。最低限、次を決めます。

• リトライ間隔：即時→数分→数十分…（段階的に伸ばす）
• 上限回数：何回で諦めるか
• 諦めた後：管理画面に「要対応」として出す（人が直す）

「要対応」の一覧は、ダッシュボードのカラム設計（テンプレート）と同じで、
誰が見て、何をすれば解決するか（再送/手動反映/相手に連絡）が分かる列にします。

4. 部分成功を扱う：片方だけ成功したときの“整合”を決める

連携で厄介なのは「相手には通ったが自分に反映されていない」などの部分成功です。
このとき必要なのは、整合を取り直す手段です。

• 照合：外部IDをキーに状態を再取得して突合
• 補正：差分だけ反映（重複防止が前提）
• 保留：確定せず“保留”として人が判断（保留設計）

業務フローとしては、担当者割当（割当ロジック）と合わせ、
“連携エラーの担当”を明確にしておかないと、誰も触らず滞留します。

5. セキュリティ：連携は入口なので最初に押さえる

外部連携は「外からデータが入る入口」です。最低限、次を押さえます。

• 署名検証（可能なら）／認証情報の扱い
• IP制限やレート制限（必要なら）
• ログの保持（何が届いてどう処理したか）

セキュリティ観点の整理は 権限・ログ設計 と同じ発想で、 “誰がいつ何をしたか”が追えるようにします。

業種別での典型例

製造業（不具合受付・RMA・技術問い合わせ）

不具合受付（RMAフォーム）のように添付や条件が多い領域は、
入力不足が恒久的失敗になりやすいです。先にバリデーションを強め、失敗時の“直し方”を提示すると運用が回ります。

物流（見積・受注・ステータス公開）

荷主向けの公開（ステータス公開）などは、重複や欠落が信頼に直結します。
冪等性と監視（止まったことを見える化）をセットで入れるのが安全です。

まとめ

外部連携は失敗します。だからこそ、再送・冪等性・部分成功の整合・監視の4点を最初から設計に入れるべきです。
「止まらない」より「止まっても戻れる」を優先すると、運用が安定します。