外部インターフェース一覧｜7つの項目と書き方

はじめに

新しい受注システムの画面は、ほぼ完成した。決済APIも会計システム連携も、担当チームごとに設計書がある。ところが結合テストの直前、倉庫へ渡すCSVだけが誰の担当にも入っていないと分かった。

外部連携の事故は、個別仕様の書き方より前に起きる。「連携はいくつあるのか」「どちらが送るのか」「失敗したら誰が戻すのか」を、全員が同じ一覧で見ていないからだ。

外部インターフェース一覧は、APIのURLを並べる表ではない。API、ファイル、メッセージを横断し、システム境界を合意する台帳である。最初は7つの項目群で十分だ。

外部インターフェース一覧は「数と境界」を決める

IPAの機能要件の合意形成ガイド・外部インタフェース編は、外部インターフェース一覧を、対象システムと関連システムの間で行うデータ授受の一覧と定義する。目的には、連携の概要を一目で把握することと、他の工程成果物にあるインターフェース数との不一致を見つけることが挙げられている。

ここで大事なのは「一覧」と「詳細仕様」を分けることだ。

一覧では、連携の数、相手、方向、方式、タイミング、データ、責任を一行で比較する。詳細仕様では、APIのエンドポイント、項目の型、CSVの桁数、エラーコードなどを決める。最初から詳細仕様を書き始めると、一本ずつは詳しくても、そもそも抜けた連携を発見できない。

メール添付や画面への手動登録は、IPAが定義するシステム間インターフェースとは分ける。ただし、業務上のデータ受け渡しを漏らさないため、別の「手動連携」区分で同じ棚卸しに置く。自動連携の本数には数えず、自動化候補と責任境界を確認するために使う。

たとえば「会計システム連携」という一行では粗すぎる。売上確定を送る処理と、入金結果を受け取る処理は、方向もタイミングも失敗時の責任も違う。別の連携IDを付けるべきだ。

一行の単位は、送受信先、業務イベント、データ契約、方式・接続点、サービス条件が同じかで判断する。どれかが異なれば分ける。

一覧へ書く7つの項目

1. 連携ID・名称・目的

連携ごとに変更されないIDを付ける。名称は「顧客連携」のような名詞だけにせず、「ECからCRMへ新規顧客を登録」のように方向と動詞を含める。

目的も一文で書く。「顧客情報を連携する」では処理の説明にしかならない。「営業担当が注文当日に顧客へ連絡できるようにする」まで書けば、遅延や停止の業務影響を判断できる。

IDは詳細仕様、テストケース、監視項目、障害票でも共通して使う。設計書名が変わっても追跡できるよう、IF-CUST-001のような業務領域を含む番号にすると扱いやすい。

2. 送信元・受信先・責任者

システム名だけでは足りない。どの機能や構成要素が送り、どこが受けるのかを書く。外部SaaS、社内基盤、委託先など運用主体も添える。

特許庁が公開する外部インタフェース一覧の様式案も、自サブシステム、外部システム連携、他システムを分け、名称と構成要素を対応づけている。境界の両側を明示する考え方は、一般の案件にも使える。

責任者は「開発チーム」ではなく役割で置く。送信側のデータ責任者、受信側の取り込み責任者、障害時の一次連絡先を決める。会社をまたぐ場合は、問い合わせ可能な時間帯も必要だ。

3. 方向・開始条件・頻度

送信、受信、双方向のどれかを書く。双方向なら、要求と応答が一つの処理なのか、互いに独立した二本の連携なのかを分ける。

「日次」だけでは実装も運用も決まらない。毎日2時、営業日締め後、注文確定時、利用者の手動操作時など、開始条件を書く。頻度に加え、通常件数、最大件数、繁忙期も置く。

時刻にはタイムゾーンを付ける。締め処理との前後関係も記録する。

4. 連携方式・プロトコル・認証

API、Webhook、SFTP上のファイル、オブジェクトストレージ、メッセージキュー、画面からの手動登録など、方式を揃えた語彙で記録する。

APIならHTTPS、利用主体の認証、許可する操作の認可を分ける。たとえば「OAuth 2.0 Client Credentialsでクライアントを認証し、売上登録スコープだけを許可」と書く。ファイルなら配置場所と受け渡し手段、メッセージならトピックやキューの所有者を書く。VPNやIP制限の有無、資格情報の発行者と更新者も一覧で見えるようにする。

詳細なAPI契約はAPI仕様書の書き方を5つの契約に分けた記事へ渡す。一覧に全パラメータを詰め込む必要はない。代わりに、参照する詳細仕様のURLと版を持たせる。

5. データ・形式・規模

データ名はファイル名やJSON名ではなく、業務上の意味で書く。「orders.csv」ではなく「前日確定した出荷指示」のようにする。形式はJSON、CSV、XML、画像などを記録し、詳細な項目定義への参照を付ける。

規模には平均と最大を置く。件数、最大サイズ、ピーク時の要求数を方式に応じて選ぶ。

個人情報、決済情報、営業秘密を含むかも列にする。データ分類が見えれば、暗号化、保存期間、ログへの記録範囲、テストデータの匿名化を検討しやすい。

データがどの業務から生まれ、どこへ流れるかは、データフロー図を要件へ変える5ステップと組み合わせると抜けを見つけやすい。

6. 成功・失敗・再処理

正常終了の条件を一行で置く。HTTP 200が返ることだけでは弱い。受信側で登録が完了し、連携IDに対応する処理結果を照合できるところまでが成功かもしれない。

失敗時は、検知方法、再試行の有無、重複防止、人へ通知する条件を書く。一覧では「要求IDで重複排除、3回失敗で通知」までにとどめる。業務キーや処理済み記録の詳細は、前述のAPI仕様書で定義する。

7. サービス条件・監視・変更

許容遅延、利用可能時間、保守時間、復旧目標を決める。翌営業日でよい連携と、即時応答が必要な連携を分ける。

監視では、成功件数、失敗件数、滞留、最終成功時刻、処理時間のうち何を見るかを決める。通知先と、何分後に誰が対応するかも必要だ。

外部サービスの仕様変更に備え、提供者、利用中の版、廃止予定日、変更通知の受信者を置く。OpenAPI Specification 3.1.1のような機械可読な詳細仕様がある場合も、どの版を本番で使うかは一覧側で追跡する。

外部インターフェース一覧の記入例

一覧は横に広がりやすい。レビュー用には、次の粒度で始めるとよい。

この表は詳細設計の代わりではない。IF-ORD-001から認証仕様、項目定義、エラー設計、結合テストへ移動できるよう参照先を別列で持つ。

実管理では、目的、方向、データ分類、通常規模、最大規模、保守時間、責任者、詳細仕様URLを独立列にする。上の表はレビュー用の最小表示である。表計算でも管理できるが、列名と選択肢を固定し、自由記述を増やしすぎない。

業務フローから漏れを探す3回のレビュー

一覧の初版は会議室で思い出した連携だけになりやすい。異なる資料から3回照合する。

1回目は業務フローを見る。各工程で、別システムへ情報が渡る箇所に連携IDがあるか確認する。メール添付や手動アップロードは「手動連携」として別区分に置き、自動インターフェース数と混ぜない。

2回目はシステム構成図とデータフロー図を見る。矢印ごとに一覧の行があるか、一覧の行ごとに矢印があるかを往復する。監視、認証、バックアップ向けの連携も拾う。

3回目は見積書とテスト計画を見る。連携数が一致するか、各IDに実装担当と結合テストがあるかを照合する。IPAのガイドが工程成果物間の数を比べるのは、まさにこのためだ。

レビューでは、詳細が未確定でも行を消さない。「未定」として責任者と決定期限を置く。空欄のまま設計へ進むより、未決事項が見えるほうが安全である。

詳細仕様へ渡す前のチェックリスト

外部インターフェース一覧を共有する前に、次を確認する。

• API以外のファイル、メッセージ、手動連携も載っている
• 送信元と受信先の構成要素、運用責任者が分かる
• 開始条件、頻度、通常規模、最大規模がある
• 正常終了と失敗時の再処理を説明できる
• 個人情報などのデータ分類が付いている
• 詳細仕様、テスト、監視へ同じ連携IDで追跡できる
• 業務フロー、構成図、見積書との件数差がない

外部インターフェース一覧の価値は、表を埋めたことではなく、境界を越える仕事を数えられることにある。数が決まり、責任と失敗時の動きが見えれば、開発会社は工数を分け、利用部門は業務影響を判断できる。

Atsumellでは、散在する業務資料から連携、データ、例外、責任分界を整理し、実装とテストへ渡せる仕様づくりを支援している。外部連携の棚卸しから始めたい場合は、お問い合わせフォームから相談してほしい。

関連記事

• AIのセキュリティは要件で守る
• 要件定義のヒアリング｜7つの質問
• エージェント駆動開発とは何か — バイブコーディングの「次」を整理する