外部連携（CSV/EDI/API）設計ガイド｜データマッピング・Webhook・再送で事故を防ぐ

外部連携は「一度つないだら終わり」にことがありますが、実際は例外や変更が必ず出ます。 壊れない連携にするには、項目の対応表（マッピング）だけでなく、失敗時の扱い、再送、二重処理対策までをセットで決める必要があります。

連携方式ごとの特徴（ざっくり）

• CSV：手軽だが、運用ルールがないとミスが増える
• EDI：業界ルールに沿うが、変更が重い
• API：リアルタイム化できるが、失敗時の設計が要になる

データマッピング設計で決めること

連携事故の多くは「値の意味が違う」「例外値が処理できない」「コードがズレる」から起きます。対応表は“項目名”だけで終わらせないのがコツです。

マッピング表に入れるべき列

• 送信側項目名／受信側項目名
• 型（文字・数値・日付）／桁数／必須
• コード体系（例：01/02、A/B、true/false）
• 変換ルール（トリム、全角半角、日付フォーマットなど）
• 例外値（空、0、N/A、未定…）の扱い

失敗前提の設計（これがないと運用が止まる）

• エラーの一覧化：失敗データを一覧で確認できる
• 再送の仕組み：1件単位／バッチ単位で再実行できる
• 保留キュー：人が判断するデータを隔離する（例外を混ぜない）

Webhook・再送・冪等性（API連携の要点）

Webhookは便利ですが、同じ通知が複数回届く前提で作らないと二重処理が起きます。再送と冪等性（同じ処理を繰り返しても結果が変わらない）をセットで考えます。

よくある事故

• Webhookが2回届いて、同じ注文が2回作成された
• タイムアウトで失敗扱い→実は相手側は成功していて二重更新
• 連携IDがなく、突合できずに手作業が増える

基本の対策

• 外部ID（ユニークキー）を必ず保持する
• 処理済みイベントIDを記録し、重複を弾く
• 「成功/失敗」の判定をログで確認できるようにする

連携テスト（受入）の現実的な進め方

• 正常系だけでなく、例外系（空・桁超え・未知コード）を先に用意する
• 「やり直し」手順（再送・取消）をテスト項目に入れる
• 本番データの一部を匿名化して流し、ズレを早期に出す

まとめ

外部連携は「つながること」より「壊れたときに戻せること」が大事です。 マッピング表、例外の隔離、再送、二重処理対策までを最初から入れておくと、運用が静かになります。