インターフェース設計書の書き方 記載項目と連携方式別のサンプル・確認すべき点

「結合テストに入った途端、データの形式が違うと判明した」「連携先から仕様を聞かれても、まとまった文書がない」。システム間の連携を扱う現場で、繰り返し起きている状況です。

インターフェース設計書は、どのデータを、どこからどこへ、どの形式で、いつ渡すかを定義した文書です。IF設計書、インターフェース仕様書、IF定義書といった呼び方もされます。

この文書が曖昧なままだと、結合の段階になって初めて食い違いが発覚します。しかも原因は技術的な難しさではなく、桁数や日付形式といった細部の認識違いであることが大半です。

この記事では、記載すべき項目を整理したうえで、連携方式ごとの書き方、データ項目定義の作り方、見落とされやすい記載、そして相手先との合意の進め方までを順に扱います。

確認したいポイント	結論	詳細
何を書く文書？	システム間の連携方法を定義する	どのデータを、どこからどこへ、どの形式でいつ渡すかを明文化した設計書です。
いつ作る？	基本設計（外部設計）の工程	要件定義で洗い出した連携を設計工程で具体化し、実装前に相手先と合意します。
最重要の項目は？	データ項目定義とエラー処理	項目の対応関係と、異常時の挙動です。後者が抜けると本番障害に直結します。
トラブルの原因は？	文字コードや形式の認識違い	桁数、日付形式、文字コード、必須の扱い。細部の食い違いが結合テストで表面化します。

この記事でわかること

• インターフェース設計書の役割と、他の設計書との関係および作成のタイミング
• 記載すべき7つの項目と、それぞれに何を書くのか
• API、ファイル、データベースなど連携方式ごとの記述の違い
• データ項目定義（項目マッピング表）の作り方と書くべき属性
• 異常系や文字コードなど、見落とすと結合テストで手戻りになる記載

システム開発とAI活用の進め方をまとめた資料を無料で配布しています 要件整理の進め方、開発の依頼範囲や体制の決め方、費用と期間の目安を1冊にまとめました。 社内での検討材料としてご活用いただけます。 ＞ 資料請求はこちら ※オンライン完結／しつこい営業は一切いたしません

インターフェース設計書とは

インターフェース設計書は、複数のシステムやモジュール間でやり取りするデータの内容、形式、通信方式、エラー処理などを定義した文書です。

業務システムは互いに連携して動いています。基幹システムから会計システムへ売上データを渡す、勤怠システムから給与システムへ月次データを送る。この受け渡しの取り決めを明文化したものが、この設計書になります。

呼び方の違い

同じものが複数の名前で呼ばれています。インターフェース設計書、インターフェース仕様書、IF定義書、外部インターフェース設計書。いずれも実質的に同じ内容を指します。

組織によっては、設計書と仕様書を区別している場合もあります。設計書は作る側の視点、仕様書は使う側の視点という整理です。ただし厳密な使い分けが定着しているわけではありません。

打ち合わせでは、どの文書を指しているかを確認するのが安全です。名称の正解を探すより、プロジェクト内で呼び方を統一するほうが実務的です。

どの工程で作るのか

作成するのは基本設計、あるいは外部設計と呼ばれる工程です。要件定義で「どのシステムと連携するか」を洗い出し、設計工程で「どう連携するか」を具体化します。

IPAが公開する共通フレーム2013は、システムのライフサイクルを通じて必要な作業項目と役割を包括的に規定した枠組みです。関係者が同じ言葉で話せるようにすることを目的としており、工程と成果物の対応を整理する際の拠り所になります。

実装より前に確定させることが前提です。実装しながら決めていくと、相手先の作業も止まります。連携相手が別会社であれば、その影響はさらに大きくなります。

他の設計書との関係

インターフェース設計書は、基本設計書の一部として位置づけられることが一般的です。画面設計書、帳票設計書、データベース設計書と並ぶ成果物になります。

参照関係としては、要件定義書で定めた連携要件を根拠に作成し、データベース設計書の項目定義と整合させます。独立した文書ではなく、他の設計書と対応しているという前提で作ります。

文書の体裁や版管理の考え方については要件定義書のフォーマット｜表紙・改訂履歴・ID体系・表のレイアウトの決め方も参考になります。

なぜ必要なのか

「実装しながら合わせればよい」という進め方が通らない理由を整理します。この文書がないことによる損失は、想像より大きくなります。

結合時のトラブルを防ぐ

最も直接的な目的です。送信側と受信側で認識が違っていると、つないだ瞬間に動きません。

実際に起きる食い違いは、技術的に難しいものではありません。日付が「20260914」なのか「2026/09/14」なのか。金額に小数点を含むのか。コード値の前ゼロを保持するのか。文書に書かれていなければ、双方が自分の常識で実装します。

そしてこの種の問題は、どちらが直すのかという議論から始まります。技術的な修正より、合意形成のほうに時間がかかるというのがこの工程の特徴です。

並行開発を可能にする

インターフェースが確定していれば、送信側と受信側が同時に開発を進められます。相手の実装が終わるのを待つ必要がなくなります。

確定した仕様があれば、相手側の応答を模擬するプログラムを作って検証できます。実機がつながる前に、自分側の実装を仕上げておけます。

複数の会社が関わる案件では、この効果が特に大きくなります。仕様が固まらないと、相手会社は工数を確保できません。着手が遅れ、全体のスケジュールが押します。

保守と障害調査の根拠になる

稼働後も使われ続ける文書です。障害が起きたとき、正しい挙動が何かを判断する根拠になります。

「このデータが連携されていないのは異常か、仕様どおりか」という判断は、文書がなければつきません。担当者が異動していれば、誰にも分からなくなります。

移行時のデータ検証でも参照されます。新旧システムで同じデータが渡っているかを確認する際、項目の対応表が必要になります。

記載すべき項目

決まった様式はありませんが、押さえるべき項目は共通しています。次の7つを埋めることから始めます。

1. 基本情報とインターフェース一覧

最初に必要なのは全体像です。このシステムが外部とやり取りするすべての接点を一覧にします。

【インターフェース一覧の列】

・IF-ID（例：IF-001）

・インターフェース名

・送信元システム／受信先システム

・連携方式（API／ファイル／DB など）

・方向（送信／受信／双方向）

・タイミング（リアルタイム／日次／月次）

・対象データと想定件数

・担当（自社／相手先）

この一覧が、そのままテスト範囲の合意資料になります。一覧が漏れていれば、そのままテストの漏れになります。相手先とも共有して認識を揃えます。

個々のインターフェースの詳細は、IF-IDごとにページを分けて記述します。一覧が目次の役割を果たす構成です。

2. 処理概要

そのインターフェースが何をするのかを、文章で数行にまとめます。何のデータを、どこからどこへ、どんなタイミングで連携するのか。そこでどういう加工が行われるのかを記述します。

加工には、特定の条件での絞り込み、複数データの結合、項目を使った計算、明細から集計単位への変換などがあります。加工がある場合は必ず明記します。

処理が複雑な場合は、入力、処理、出力を明記したフロー図を添えます。文章だけでは流れが追えなくなるためです。

3. 連携方式と接続情報

技術的な取り決めを記述します。方式によって書く内容が変わるため、詳細は次章で扱います。

共通して必要なのは、接続先の情報です。URL、ホスト名、ポート、パス、認証方式。環境ごとに異なるため、検証環境と本番環境の両方を記載します。

接続情報は手打ちさせない形で書くことが実務上の配慮です。コピーできる形で載せておけば、入力ミスによる事故を構造的に減らせます。

4. データ項目定義

この文書の中核です。やり取りする項目を1つずつ定義します。詳しい書き方は後の章で扱います。

送信側と受信側で項目名が違う場合は、その対応関係を表にします。これを項目マッピングと呼びます。加工が入る項目には、その変換内容も併記します。

5. エラー処理とリトライ

抜けやすく、抜けると本番障害に直結する項目です。異常が起きたときにどう振る舞うかを定義します。

• 通信エラー時：リトライするか、何回まで、何秒間隔で
• タイムアウト：何秒で打ち切り、その後どうするか
• 業務エラー時：エラーコードの体系と、それぞれの意味
• 不正データ受信時：該当行だけ飛ばすか、処理全体を止めるか
• エラー時の通知：誰に、どの手段で知らせるか

リトライの設計は特に注意が必要です。同じ処理を再送した結果、二重登録が発生するという事故は珍しくありません。重複を防ぐ仕組みまで含めて定義します。

6. 非機能要件

性能や可用性に関する取り決めです。数値で書かないと検証できません。

記載するのは、想定データ件数と最大件数、許容する応答時間、同時接続数の上限、処理完了の期限です。「なるべく速く」では、テストの合否を判定できません。

IPAが公開する非機能要求グレードでは、可用性、性能・拡張性、運用・保守性など6つの大項目について要求レベルを段階的に整理する枠組みが提供されています。この分類に沿って確認すると、抜けを防げます。

7. 運用と監視

稼働後の扱いを定義します。ログをどこに何日分残すか、どう監視するかを決めておきます。

バッチ連携であれば、実行スケジュール、実行順序、前後の依存関係も記載します。祝日や年末年始の扱いも決めておく必要があります。

再実行の手順も書きます。障害で途中停止した場合に、最初からやり直すのか途中から再開するのか。運用担当者が判断できる状態にしておきます。

連携要件の整理からご相談いただけます 書き方は分かっても、自社の連携で何が抜けているかの判断は別の問題です。要件の棚卸しからご一緒する30分の無料相談をご用意しています。 ▶ 相談予約はこちら ※オンライン完結／秘密厳守／助成金活用のご相談も歓迎

連携方式別の書き方

方式ごとに記述すべき内容が変わります。代表的な4つについて整理します。

API連携

リアルタイムでシステム同士がやり取りする方式です。リクエストとレスポンスを対で定義します。

【記載項目】

・エンドポイントURL（環境ごと）

・HTTPメソッド（GET／POST など）

・認証方式（APIキー／Bearerトークン／OAuth2 など）

・リクエストヘッダ（Content-Type など）

・リクエストパラメータ／ボディの項目定義

・レスポンスの項目定義（ステータスコードごと）

・エラーコード一覧と意味

・流量制限（1分あたりの呼び出し上限など）

正常系だけでなく、400番台と500番台のレスポンス形式も定義します。ここが書かれていないと、受信側はエラー処理を実装できません。

なお、API連携についてはOpenAPI形式で定義ファイルを作成する方法もあります。Excelの設計書と二重管理にならないよう、どちらを正とするかを決めておきます。

ファイル連携

CSVや固定長ファイルを受け渡す方式です。ファイルの中身だけでなく、受け渡しの運用まで定義します。

【記載項目】

・ファイル名の命名規則（日付や連番の付け方）

・配置先のパスと権限

・転送方式（SFTP／共有フォルダ など）

・文字コード（UTF-8／Shift_JIS など）

・改行コード（CRLF／LF）

・区切り文字と囲み文字

・ヘッダー行／トレーラー行の有無と内容

・レコードレイアウト（項目の順序と桁数）

・0件時の扱い（空ファイルを置くか、置かないか）

0件時の扱いは必ず決めます。ファイルが届かないのが正常なのか異常なのかが分からないと、受信側は判断できません。

あわせて、同じファイルが二重に配置された場合の重複防止と、取り込み失敗時の退避・再取り込みの手順も記載します。

データベース連携

相手システムのデータベースを直接参照する、あるいは中間テーブルを介する方式です。

記載するのは、接続先のデータベース名、対象テーブルとビュー、参照に使うアカウントと権限、取得条件です。参照するSQLを記載する場合もあります。

中間テーブルを使う場合は、書き込む側と読み取る側の責任範囲を明確にします。処理済みフラグの更新を誰が行うか、いつデータを削除するかを決めておかないと、データが溜まり続けます。

メッセージ・イベント連携

メッセージキューやイベント通知を介した非同期の連携です。送信と受信のタイミングが分離されるという特性を前提に定義します。

記載するのは、キューやトピックの名称、メッセージの形式、順序保証の有無、再送の条件です。同じメッセージが複数回届く可能性があるため、重複を許容する設計かどうかを明記します。

処理できなかったメッセージの扱いも決めます。破棄するのか、別のキューに退避するのか。運用時の対応手順まで含めて記載します。

データ項目定義の書き方

この文書の価値を決める部分です。項目一覧の粒度が、結合テストの成否を左右します。

項目マッピング表の作り方

送信元と受信先の項目を左右に並べ、対応関係を示します。加工が入る場合は、その内容を中央の列に記述します。

No｜送信元項目　　　｜型・桁　　｜受信先項目　　　｜加工内容

1 ｜juchu_no　　　 ｜文字 10　 ｜order_id　　　  ｜そのまま

2 ｜juchu_date　　 ｜日付　　　｜order_date　　  ｜YYYYMMDDに変換

3 ｜kingaku　　　　｜数値 10,0 ｜amount　　　　  ｜税抜→税込に計算

4 ｜tokui_cd　　　 ｜文字 6　　｜customer_code　 ｜コード変換表を参照

5 ｜（固定値）　　 ｜－　　　　｜system_id　　　 ｜’SALES’を設定

5行目のような固定値も明記します。受信側で必要だが送信元には存在しない項目は、何を設定するかを決めておきます。

各項目に書くべき属性

項目名と型だけでは足りません。次の情報が揃って初めて実装できます。

• データ型：文字列、数値、日付、真偽値
• 桁数：最大長。数値なら整数部と小数部
• 必須／任意：任意の場合、未設定時の扱い（空文字かnullか）
• 形式：日付や電話番号などのフォーマット
• 取り得る値：コード値の一覧、数値の範囲
• 業務上の意味：その項目が何を表すか

最後の項目を省略しないでください。「区分1」という項目名だけでは、受信側は何のデータかを判断できません。業務上の意味が書かれていることで、異常値に気づけるようになります。

加工・変換ルールの記述

加工がある項目は、計算式や条件を具体的に書きます。「適切に変換する」では実装できません。

日付形式の変換、文字コードの変換、単位の換算、複数項目の結合、条件による値の切り替え。それぞれ、入力と出力の例を添えると誤解が減ります。

変換できない値が来た場合の扱いも決めます。想定外のコード値を受け取ったら、エラーにするのか既定値を設定するのか。ここが未定義だと、実装者が独自に判断します。

コード値の対応表

システム間でコード体系が違う場合、変換表を別に用意します。項目マッピング表の中に書き込むと読みにくくなります。

【区分コード変換表】

送信元　｜受信先　｜意味

01　　　｜NEW　　 ｜新規受注

02　　　｜REP　　 ｜再注文

09　　　｜CAN　　 ｜キャンセル

表に存在しない値を受け取った場合の扱いも併記します。この一文があるかどうかで、本番障害の有無が変わることがあります。

見落とされやすい記載

結合テストで発覚する問題は、ほぼ決まった箇所に集中します。事前に確認しておきたい項目を挙げます。

文字コードと改行コード

ファイル連携で最も多いトラブルです。送信側がShift_JIS、受信側がUTF-8を想定していたというだけで、文字化けが発生します。

あわせて確認すべきは文字種です。機種依存文字、外字、絵文字、半角カナ、サロゲートペアを含む文字。これらが渡ったときの挙動は、実データで試さないと分かりません。

改行コードも明記します。WindowsとLinuxで異なるため、環境をまたぐ連携では必ず問題になります。

タイミングと処理の順序

リアルタイムとバッチが混在するシステムでは、順序が問題になります。先に届くはずのデータが後から届いたときの挙動を定義します。

マスタデータと明細データを別々に連携する場合、マスタが未登録の状態で明細が届く可能性があります。エラーにするのか、保留して後で処理するのかを決めます。

日をまたぐ処理の基準日も明記します。深夜に実行されるバッチで、どの日付を業務日として扱うかが曖昧だと、集計がずれます。

データ量とピーク

少件数では動いても、本番相当の量を流すと破綻することがあります。想定件数と最大件数を明記します。

特に注意が必要なのが、月次や年次のピークです。通常は1日100件でも、月末に1万件が集中するなら、その前提で設計する必要があります。

1回の連携で送る上限件数も決めます。上限を超える場合に分割するのか、エラーにするのかを定義しておきます。

認証情報の管理

認証方式は書かれていても、その情報をどう管理・更新するかが書かれていないことが多くあります。

APIキーやパスワードの受け渡し方法、有効期限、更新時の手順。証明書を使う場合は、その有効期限と更新の担当者を明記します。

証明書の期限切れによる障害は、数年後に必ず起こります。設計書に期限を記載し、更新の責任者を決めておくことが対策になります。

自社側の作業範囲

発注側として確認したい観点です。連携相手が既存ベンダーや外部サービスの場合、誰が窓口になって調整するのかを明確にします。

既存システムの仕様確認、接続情報の取得、ファイアウォールの設定依頼。これらは発注側が動かないと進まない作業です。設計書に役割を記載しておきます。

委託時の役割分担についてはシステム開発の外注とは｜メリット・デメリット、費用相場、外注先の種類と選び方でも整理しています。

作成と合意の進め方

書くこと自体より、相手先と合意することが本質です。合意なき設計書は、単なる希望の表明にとどまります。

インターフェース一覧から始める

詳細を書き始める前に、まず全体の一覧を作って関係者で確認します。ここで漏れがあると、後から追加のたびに調整が発生します。

一覧は要件定義書の連携要件から機械的に作成できます。あわせて、既存システムの連携も棚卸ししておくと、想定外の接点が見つかることがあります。

優先順位も付けておきます。件数が多い連携、更新系の連携、外部サービスとの連携は、早めに仕様を固める必要があります。

サンプルデータを添える

文章だけの仕様書は、必ず解釈の幅を生みます。実際の値が入ったサンプルを1件添えるだけで、認識の差は大きく減ります。

「日付：YYYYMMDD形式」と書くより、「日付：20260914」と書くほうが誤解が起きません。CSVであれば、実際のファイルを数行分添付します。

APIであれば、リクエストとレスポンスのサンプルを併記します。正常系と代表的なエラー時の両方を用意しておくと、実装時の確認が速くなります。

相手先と読み合わせる

文書を送って「確認してください」で済ませると、読まれないまま合意扱いになります。関係者が集まり、声に出して読み合わせるという場を設けます。

この場で認識の違いが表面化します。同じ項目名を別の意味で理解していた、必須の扱いが違っていた。結合テストで発覚するより、圧倒的に安く済みます。

合意した内容は、版数を上げて記録します。要件の書き方や粒度については要件定義の例｜システム種類別の要件例と、機能要件・非機能要件の書き換え集も参考になります。

運用で押さえること

設計書は作った時点では未完成です。変更に追随できる仕組みが必要になります。

版管理と改訂履歴

複数の会社がやり取りする文書であるため、版の混乱が起きやすくなります。表紙に版数と日付を記載し、改訂履歴の表を設けます。

改訂履歴には、版数、日付、変更内容、変更理由、承認者を記録します。「どの版で合意したのか」が後から追える状態にしておきます。

保管場所は1か所に定めます。メール添付でやり取りすると、各社が別の版を見ている状態になります。

変更時の周知

インターフェースの変更は、相手側の実装に直接影響します。項目の追加、桁数の変更、コード値の追加。いずれも連携先の修正が必要になる可能性があります。

変更の手続きをルールとして決めておきます。誰が起案し、誰が承認し、いつまでに周知するか。影響範囲の確認を手順に含めることが重要です。

稼働後の変更については、後方互換性を保つかどうかも論点になります。項目を追加するだけなら影響は小さいものの、既存項目の意味を変えると相手側が壊れます。

納品物としての扱いを決める

開発を外部に委託している場合、この設計書が納品対象に含まれているかを契約段階で確認します。

含まれていないと、保守や機能追加の際に外部に問い合わせることになります。自社で保守する可能性があるなら、必ず納品物に含めます。

あわせて、更新の責任範囲も決めます。稼働後に仕様が変わった場合、誰が設計書を更新するのか。ここが曖昧だと、文書が実態から乖離していきます。

まとめ

インターフェース設計書は、システム間の連携方法を定義する文書です。基本設計の工程で作成し、実装前に相手先と合意することが前提になります。

記載すべきは、インターフェース一覧、処理概要、連携方式と接続情報、データ項目定義、エラー処理、非機能要件、運用と監視の7項目です。

最も抜けやすいのがエラー処理です。リトライの回数と間隔、タイムアウト、不正データ受信時の挙動。ここが未定義だと、本番障害に直結します。

そして書き方の要点は、サンプルデータを添えることです。「YYYYMMDD形式」より「20260914」と書くほうが、認識の差は確実に減ります。

まずは自社のシステムが外部とやり取りしている接点をすべて洗い出し、一覧にしてみてください。その一覧が、この設計書全体の出発点になります。

システム開発の進め方から、無料で相談できます 受け取った設計書の妥当性を判断したい、既存システムとの連携を検討したいといった段階のご相談も承っています。 営業色は一切ありません。 ▶ 相談予約はこちら ※オンライン完結／秘密厳守／助成金活用のご相談も歓迎