外部システム連携は、APIやCSVの送受信ができた時点で完了ではありません。 実務で問題になりやすいのは、通信そのものよりも、項目の意味、コード体系、例外処理、再送時の扱いです。
たとえば「納期」という項目が、片方のシステムでは希望納期、もう片方では確定納期を指していることがあります。 ステータス名が同じでも、社内側では「承認済み」、外部側では「出荷準備中」を意味している場合もあります。 このような意味のズレを残したまま連携すると、画面上は成功しているように見えても、現場では確認作業が増えてしまいます。
このページでは、外部連携を安定して運用するために、データマッピング、コード変換、冪等性、再送、エラー保留、監査ログまでを実務の順番で整理します。
データマッピングでは、項目名の対応表だけを作っても不十分です。 項目名が同じでも、意味や使い方が違うことがあるためです。 そのため、マッピング表には、項目名だけでなく意味定義、必須条件、変換ルール、例外時の扱いまで入れておく必要があります。
画面例 データマッピング管理画面
希望日、確定日、回答予定日など、似た名称でも意味を分けて記録する。
必須なら保留、任意なら空欄送信、補完可能なら変換時に補完する。
どの入力値がどの値に変換されたかをログに残す。
マッピング表では、項目名の一致ではなく、意味・変換・例外時の扱いまで確認できる状態にしておくと、運用時の確認が短く済みます。
入力項目の考え方は、項目まとめ や 見積依頼 の設計ともつながります。 外部連携では、フォームや管理画面で入力された項目が、どの意味で外部システムへ渡るのかを明確にしておくことが重要です。
カテゴリ、ステータス、担当者、拠点、顧客区分などのコード体系は、システムごとに異なるのが普通です。 片方のコード体系に無理に合わせると、どちらかの運用に負担が出ます。 そのため、外部連携では変換テーブルを持つ設計が現実的です。
変換 コード変換の代表例
Web側の「技術相談」を、外部側では「製品問い合わせ」「品質問い合わせ」に分けるなど、多対一・一対多の関係が出ます。
社内の「確認中」と外部側の「受付済み」が同じ意味とは限りません。遷移ルールも合わせて確認します。
担当者IDや拠点コードはシステムごとに異なるため、担当者マスタ・拠点マスタの対応表を持ちます。
| 変換対象 | 起きやすい問題 | 設計のポイント |
|---|---|---|
| カテゴリ | 自社側の分類と外部側の分類粒度が違う。 | 変換テーブルを持ち、多対一・一対多の関係を明示する。 |
| ステータス | 同じ「完了」でも、請求完了・作業完了・確認完了など意味が違う。 | ステータス名だけでなく、遷移条件と完了条件を確認する。 |
| 担当者 | 社員番号、メールアドレス、担当IDがシステムごとに異なる。 | 担当者マスタの対応表を持ち、退職・異動時の扱いを決める。 |
| 拠点 | 本社、営業所、店舗、倉庫の粒度が違う。 | 拠点コードと拠点種別を分け、外部側との対応を管理する。 |
コード体系を安定して扱う考え方は、コード体系設計 が前提になります。 外部連携だけでなく、検索・集計・CSV更新まで見据えて、内部コードと表示名を分けて管理しておくと扱いやすくなります。
外部連携では、同じデータが複数回送られることがあります。 ネットワークの不調、外部側のタイムアウト、手動再送、バッチの再実行など、原因はさまざまです。 このとき、同じリクエストで二重登録、二重通知、二重請求が起きると、運用上の影響が大きくなります。
そのため、再送されても同じ結果になるように、冪等性を最初から設計に入れておく必要があります。
二重実行防止の考え方は、冪等性 の設計とも共通します。 外部連携では特に、成功したのか、失敗したのか、外部側では登録済みなのかを確認できる状態が重要です。
外部連携は必ず失敗します。 コード変換できない、必須項目が足りない、外部APIが止まっている、タイムアウトした、添付ファイルが大きすぎるなど、理由はいくつもあります。
問題は、失敗そのものではありません。 失敗したデータが残らず、誰も気づけないことです。 そのため、失敗したデータは破棄せず、保留キューに入れて運用者が確認できるようにします。
保留 連携エラーキューの画面例
エラーキューでは、入力データ、変換後データ、エラー理由、再試行回数を確認できるようにしておくと、手動対応や再送判断がしやすくなります。
連携エラーには、自動で再送すればよいものと、人が確認してから再送すべきものがあります。 すべてを自動再送にすると、コード不一致や項目不足のようなエラーを繰り返すだけになります。 一方、すべてを手動にすると、外部APIの一時的な不調でも担当者の作業が増えます。
流れ 連携失敗から再送までの流れ
APIまたはCSVで外部システムへデータを送る。
成功、警告、失敗、タイムアウトを判定する。
失敗理由と元データを保留キューに保存する。
一時障害は自動再送、項目不備は手動修正後に再送する。
外部ID、内部ID、処理結果を監査ログに残す。
通知や段階的なエスカレーションは、エスカレーション の考え方にも近い領域です。 連携エラーを誰が確認し、何分後・何時間後に上長へ通知するかまで決めておくと、運用が止まりにくくなります。
外部連携は、社内の担当者から見ると自動でデータが変わる処理です。 そのため、ログがないと「なぜステータスが変わったのか」「どこからこの値が入ったのか」が分からなくなります。
連携の監査ログでは、送信・受信・変換・結果を分けて残します。
| ログ種別 | 残す内容 | 確認したい場面 |
|---|---|---|
| 送信ログ | いつ、どのデータを、どの外部システムへ送ったか。 | 外部側に届いているか確認したいとき。 |
| 受信ログ | いつ、どの外部システムから、どのデータを受け取ったか。 | 社内データが自動更新された理由を確認したいとき。 |
| 変換ログ | 入力値をどの変換ルールでどの値へ変換したか。 | カテゴリやステータスの意味が正しく変換されたか確認したいとき。 |
| 結果ログ | 成功・失敗、外部ID、内部ID、エラー理由。 | 再送や手動対応の履歴を確認したいとき。 |
権限とログの基本は、権限・ログ と共通します。 外部連携では、ユーザー操作ではなくシステム処理による更新も多いため、「誰が」だけでなく「どの連携処理が」更新したかを残すことが重要です。
製造業では、型式、ロット、図番、Rev、試験結果、不具合番号などが連携のキーになりやすい領域です。 Webフォーム側では「型番」だけを入力していても、基幹側や品質管理側では「品番」「図番」「ロット」「製造拠点」まで必要になることがあります。
業務像は 製造業向けWebシステム活用アイデア を前提にすると考えやすくなります。 不具合受付は RMAフォーム と合わせて、入力項目と外部側の項目定義がずれないよう、意味定義から確認します。
物流では、運賃条件、附帯作業、燃料サーチャージ、時間指定、分納、直送など、条件の意味ズレが起きやすい領域です。 見積時点の条件と、受注・配送時点の条件が同じとは限らないため、どの時点の情報を外部へ渡すのかを決めておく必要があります。
業務像は 物流向けWebシステム活用アイデア を前提にすると整理しやすくなります。 見積条件は 条件の聞き方、分納や直送を含む受注ステータスは 分納・直送 と合わせて確認すると、連携項目を決めやすくなります。
自動車販売・整備・タイヤショップでは、予約枠、作業メニュー、部品手配、ピット割当、入庫、精算などがつながります。 この場合、予約システム側のステータスと、作業管理・精算システム側のステータスが一致しないことがよくあります。
業務像は 自動車販売・整備・タイヤショップ向けWebシステム活用アイデア を前提にすると考えやすくなります。 入庫からピット割当までは、ピット割当 の状態を外部システム側へ無理に合わせるのではなく、変換テーブルで対応させる方が運用しやすくなります。
外部連携では、APIやCSVの接続よりも、データの意味を合わせる設計が重要です。 項目名だけで対応表を作るのではなく、意味定義、必須条件、変換ルール、例外時の扱いまで決めておく。 コード体系は一致しない前提で変換テーブルを持つ。 再送されても二重登録にならないように冪等性を入れる。 失敗したデータは保留キューに残し、監査ログで後から確認できるようにする。
この流れで設計しておくと、外部連携は単なるデータ送受信ではなく、現場で確認・修正・再送できる業務機能として使いやすくなります。