外部連携のデータマッピング設計｜項目・コード・例外を“壊れない形”で繋ぐ

外部システム連携は、APIが繋がった時点ではまだ半分です。
実務で壊れるのは「項目の意味ズレ」「コード体系の不一致」「例外処理不足」「再送時の二重登録」です。
この記事では、連携の“地味に痛い”事故を減らすために、データマッピング（項目対応表）をどう設計するかを整理します。

1. 連携は「項目」より「意味」を合わせる

同じ項目名でも、システムが想定している意味が違うことが多いです。
たとえば「納期」が、ある側では“希望日”、別側では“確定日”だった、などは典型です。
このため、マッピングは「項目名対応」ではなく「意味の定義」をセットで持ちます。

• 項目名（双方）
• 意味定義：この項目が何を表すか（希望/確定/見込み など）
• 必須条件：空の場合の扱い（拒否/デフォルト/保留）
• 変換ルール：形式変換（日時、数値、単位、全角/半角など）

入力側の項目整理は 項目整理 や、見積項目（見積依頼）の考え方が土台になります。

2. コード体系：一致しない前提で“変換テーブル”を持つ

カテゴリ、ステータス、担当、拠点などは、ほぼ確実に一致しません。
一致させようとして片側を無理に変えると、運用側が壊れます。
現実解は、変換テーブルを持つことです。

• カテゴリ：自社カテゴリ ↔ 外部カテゴリ（多対多になることもある）
• ステータス：遷移が違う前提で、相互に変換（遷移）
• 担当：担当IDが違うので、担当マスタの突合が必要

コード体系を崩さない考え方は コード体系設計 が前提になります。

3. 冪等性：再送で二重登録しない（最初から仕様にする）

ネットワークや外部側の混雑で、同じリクエストが再送されるのは普通に起きます。
これに耐性が無いと、二重登録・二重通知・二重請求などの事故になります。
基本は冪等性（二重実行防止）の設計です。

• 連携キー（外部ID＋種別など）を保持し、同じキーは更新扱い
• 「作成」と「更新」を分けず、“Upsert”として扱う
• 二重実行時に副作用（通知や添付生成）が増えないようにする

4. エラー保留：失敗したデータを捨てない

連携は必ず失敗します。失敗した時に「何が」「なぜ」失敗したかが残らないと、運用が止まります。
おすすめは、エラーを捨てずに“保留キュー”へ置く設計です。

• 失敗レコード：入力データ、変換後データ、エラー理由、日時、再試行回数を保存
• 再送：手動/自動（段階通知の考え方は エスカレーション に近い）
• 保留中：一覧で見える（運用者が潰せる）

5. 監査ログ：誰がいつ何を連携したかを追える

連携は、社内的には“自動で起きる更新”です。
勝手に変わったように見えるため、監査ログが無いと必ず揉めます。
ログは 権限・ログ の考え方で、次を残します。

• 送信（いつ、何を、どこへ）
• 受信（いつ、何を、どこから）
• 変換（どのルールでどう変換したか）
• 結果（成功/失敗、外部ID、内部ID）

業種別の典型

製造業（問い合わせ→技術対応→RMA）

型式・ロット・図番などの情報が連携のキーになりやすいです。
業務像は 製造業向け を前提に、
不具合受付（RMAフォーム）の入力項目と、外部（基幹・品質）側の項目定義がズレないよう、意味定義から合わせるのが重要です。

物流（見積→受注→配送）

運賃条件、附帯作業、燃料サーチャージなど、条件の意味ズレが起きやすいです。
業務像は 物流向け を前提に、
見積（条件の聞き方）と受注ステータス（分納・直送）を連携で崩さない設計が肝になります。

自動車販売・整備・タイヤショップ（予約→入庫→作業→精算）

予約枠、作業指示、部品手配、精算が繋がると、ステータス変換が難しくなります。
業務像は 自動車販売・整備・タイヤショップ向け を前提に、
入庫〜ピット割当（詰まらせない設計）の状態を、外部システム側の状態に無理に合わせず、変換テーブルで吸収するほうが運用が安定します。

インテンスでも、外部連携は“APIが繋がった”では終わらず、マッピング・変換・冪等性・保留運用まで含めて設計します。

まとめ

外部連携は、項目名より意味定義を合わせ、コード体系は一致しない前提で変換テーブルを持つのが現実的です。
冪等性と再送、エラー保留、監査ログをセットで入れると、連携は壊れにくく、運用で回る仕組みになります。