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

外部連携では、「注文を受け取った」と「受注システムへの登録が終わった」を分けて考えます。データが届いていても、取引先コードの不一致で登録できない場合や、一部の更新だけが終わる場合があるためです。接続方法に加えて、どのデータを更新し、どの状態を完了とするかを決める必要があります。

この記事は、連携方式の確認、項目対応表、受付単位、変更・取消、受入テストまでの全体設計を扱います。APIやWebhookの再試行・重複判定・結果不明の復旧は、外部API連携の設計で詳しく解説します。

CSV・EDI・APIは、異なる観点の言葉です

CSVはデータ形式、EDIは企業間で取引データを電子的に交換する仕組み、APIはソフトウェア間で機能やデータをやり取りする接点です。この3つを、必ずどれか一つだけ選ぶ分類として扱わないことが出発点です。

• CSVファイルを使う場合：列、文字コード、改行・引用符、受け渡し方法、取込時刻、同じファイルの再取込条件を決めます。
• EDIで取引先と連携する場合：採用する標準や取引先との取り決め、メッセージの種類、コード体系、通信方法、受領確認を確認します。
• APIを使う場合：提供される操作、送受信データの形式、認証、利用上限、更新のタイミング、結果の確認方法を確認します。APIだから必ずリアルタイムになるわけではありません。

例えば、取引先から受け取ったEDIデータを、自社システムに取り込むCSVへ変換する構成も考えられます。通信方法とデータ形式を分け、実際に相手側が提供する仕様を起点に検討します。CSVの形式例はRFC 4180、EDIと伝送方法の関係はRFC 1767の導入説明でも確認できます。

連携前に、更新する責任と対象を決める

• 正とするデータ：取引先名・在庫数・注文状態など、項目ごとにどちらのシステムを基準にするか。
• 処理の種類：新規登録・変更・取消のどれか。受け取った値で置き換えるのか、数量などを加算するのか。
• 対象範囲：全件か変更分だけか。一覧に存在しないデータを削除扱いにするか、変更しないか。
• 完了条件：ファイル受領・内容検証・業務登録・相手への通知のどこまでを確認するか。
• 例外への対応：誰が内容を修正し、誰が再実行し、確認待ちをどこで管理するか。

これらは接続方法だけからは決まりません。例えば同じ在庫数の「10」でも、在庫を10へ置き換える要求と、10を追加する要求では再取込時の結果が異なります。双方の担当者が同じ意味で扱えるよう、連携仕様に記録します。

項目対応、失敗データ、再送の流れが一画面で見えると、原因を追いやすくなります

下は、外部連携の管理画面を想定した静的な表示例です。項目・コード・件数は説明用の架空データで、実際には操作できません。この例では受信データ1レコードを1件とし、126件の内訳を登録完了120件・保留4件・再処理待ち2件としています。再試行の回数は件数に含めません。

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

項目名が同じでも、値の意味や更新条件が異なることがあります。対応表には、受信した値をそのまま使う条件と、変換・保留する条件を記録します。

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

• 送信側項目名、受信側項目名
• 型（文字、数値、日付）、桁数、必須条件
• コード体系（例：01/02、A/B、true/false）
• 変換ルール（前後空白削除、全角半角、日付形式変換など）
• 例外値（空、0、N/A、未定など）の扱い
• 単位、時刻の基準、更新対象、対応表の版と適用開始日

確認項目	見落としやすい点	先に決めたいこと
必須条件	相手側では任意でも、自社側では必須になることがあります。	欠けていた時にエラーにするか、保留にするかを決めます。
日付・時刻	タイムゾーンや時刻の有無でずれやすくなります。	保存形式と表示形式を分けて整理します。
コード値	同じように見えて意味が違う場合があります。	対応表を項目ごとに持つ方が安全です。
空値・例外値	空欄、0、未定の意味が違うと後で判定がぶれます。	値ごとに扱いを固定しておきます。

取引先コードの「00123」を数値として読み取ると先頭の0が失われます。また、項目が送られていない場合と空文字の場合に、「変更しない」「空に更新する」のどちらを意味するかも定義が必要です。未知のコードを既定の状態へ置き換えたり、長い備考を通知せず切り捨てたりせず、判断できない値を確認できる形で残します。

CSVはセル内にカンマや改行が入る場合もあるため、単純に改行やカンマだけで分割する前提にはしません。日付、識別子、空値などの変換例は、外部連携のデータマッピング設計も参照してください。

一部のデータが不正な時、どこまで取り込むかを決める

ファイル内の1行に不備があった時、正常な行だけ登録する方式と、ファイル全体を保留する方式があります。行が独立しているか、複数の明細で一つの注文を構成するかによって、適切な受付単位が異なります。この判断を、取込処理の実装時に暗黙で決めないことが必要です。

• 正常分を先に登録する方式：登録済み・保留の対象を記録し、再取込で登録済みの作用を重複させない。
• まとまり全体を保留する方式：ファイルや注文などの単位を決め、不備がある状態で一部だけ確定しない。
• 共通で残す情報：元ファイル・元レコードの識別子、業務ID、検証結果、処理段階、適用したマッピングの版、修正履歴。

再取込では、ファイル名だけで同じデータと判定しません。名称を変えた再送や、同じ名前での内容変更をどう識別するかを決めます。また、マッピングの変更前に失敗したデータを、どの版のルールで再処理するかも確認します。

Webhookの受領と、業務処理の完了を区別する

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

設計時に確認する例

• Webhookが2回届いて、同じ注文が2回作成された
• タイムアウトで失敗扱いになったが、実際には相手側で成功していて二重更新になった
• 連携IDがなく、どのデータがどこと対応するか分からず手作業が増えた

基本の対策

• 連携先・業務対象・個々の操作を識別するIDを記録する
• 受信済みと処理完了を分け、同じ通知が来ても未完了の処理を見失わない
• 成功・失敗・結果不明を分け、結果不明のまま新しい操作として再送しない

タイムアウト後に相手側の処理が終わっている場合もあります。再送の上限を決める前に、結果を照会できるか、同じ操作を再試行しても作用が増えないかを確認します。具体的な復旧条件と同時実行への対策は、Webhook・再送・冪等性の設計で扱います。

受入テストでは、正常な登録と例外からの復旧を確認する

連携テストは、正常に流れることの確認だけでは足りません。実際の運用では、空欄、桁超え、未知コード、取消データ、再送などの方が問題になりやすくなります。

1. 正常系のサンプルを用意する
   まず基本的な受信と保存ができることを確認します。
2. 例外系のサンプルを用意する
   空値、未知コード、桁超え、重複データなどを検証します。
3. 再送・取消の手順まで試す
   やり直しや取り消しができることを確認します。
4. 本番の形式や関係を再現したテストデータで確認する
   個人情報や秘密情報を使わず、コード体系、明細の関係、件数などの条件を再現します。

テスト項目	見たいこと	理由
空値・未定値	エラーか保留か	人の判断が必要なデータを分けられるか確認しやすくなります。
未知コード	落ち方と通知方法	相手側の仕様変更に早く気づきやすくなります。
重複イベント	二重登録されないか	Webhook連携では特に重要です。
再送・取消	やり直しが可能か	運用で止まらない仕組みに近づけやすくなります。
一部だけ不正なファイル	決めた受付単位で登録・保留されるか	正常分が消えたり、注文の明細が不足したまま確定したりしないか確認します。
結果不明・処理途中の停止	外部の結果と未完了の工程を確認できるか	一律の再実行による重複と、処理の取りこぼしを確認します。
仕様変更後の再取込	想定したマッピングの版で処理されるか	同じ元データを異なる意味で処理していないか確認します。

最初から全部自動化せず、手動確認の場所を残す方が安全なこともあります

外部連携では、自動化を進めるほど便利に見えますが、条件が複雑な領域では人の判断を残した方が安定することがあります。例えば次のような場面です。

• 相手先ごとにコード体系が微妙に違う
• 取消や修正の頻度が高い
• 本番データの揺れが大きい

この場合は、正常系だけ自動化し、例外は保留キューに入れて確認する方が、全体として扱いやすくなります。

まとめ

外部連携では、接続仕様と、データの意味・更新条件の両方を決めます。受信・検証・業務登録・通知を分けて記録すると、どの工程が終わり、何を確認すべきかを判断できます。

見直しでは、項目対応表、全件・差分の扱い、一部不正時の受付単位、結果不明の確認方法を確認します。既存の連携を変更する場合は、適用日とマッピングの版を記録し、処理待ちのデータや相手側の運用への影響も確認してから切り替えます。