自社システムと外部サービスをAPI連携するとき、発注前に整理すべき情報
- 3 日前
- 読了時間: 11分
更新日：2 日前
「今使っている業務システムと、新しく導入するクラウドサービスをAPIでつなぎたい」。そんなとき、開発会社へ何を伝えれば見積や設計を進められるのでしょうか。
APIの技術仕様を発注側ですべて理解する必要はありません。重要なのは、何のために、どのデータを、いつ、どちらへ連携したいのかを整理することです。
はじめに：「APIでつなぎたい」だけでは開発範囲は決まらない
業務システムと外部サービスを連携したい場面は増えています。
たとえば、
自社の顧客情報を営業支援サービスへ連携したい
ECサイトの注文情報を基幹システムへ取り込みたい
予約システムと会員システムを連携したい
決済サービスの結果を自社システムへ反映したい
外部サービスに登録された情報を自社の管理画面でも確認したい
といったケースです。
外部サービス側にAPIが用意されていれば、「あとは開発会社へAPI連携を依頼すればよい」と考えたくなります。
しかし、APIが存在することと、希望する業務をそのまま実現できることは別です。
外部サービスには、取得・登録できるデータ、処理できるタイミング、利用条件などの仕様があります。
一方、発注する事業会社には、
「注文後すぐに反映してほしい」
「夜間にまとめて連携できればよい」
「失敗したら担当者が再実行したい」
といった業務上の要求があります。
API連携では、外部サービスに何ができるのかと、自社の業務で何を実現したいのかを突き合わせることが重要です。
結論：発注前に整理したいのは「技術仕様」より業務側の情報
API連携を相談する前に、認証方式やリクエスト形式まで発注側で決める必要はありません。
まず整理したいのは、次の7点です。
何を実現したいのか
どのシステムと、どのサービスをつなぐのか
何のデータを連携するのか
どちらからどちらへデータを送るのか
いつ・どのくらいの速さで反映したいのか
連携に失敗したとき、業務としてどうしたいのか
外部サービスの契約・API資料を確認できるか
この情報があると、開発会社側で、
APIで実現可能か
追加の仕組みが必要か
既存システムのどこを変更するのか
技術調査が必要な部分はどこか
を確認しやすくなります。
最初から完璧な要件書を作ることより、業務としてどうなってほしいのかを説明できることの方が重要です。
発注前に整理したい7つの情報
1. 何を実現したいのか
最初に整理したいのは、APIの話ではなく業務上の目的です。
たとえば、
ECサイトで受けた注文を基幹システムへ自動登録し、担当者による二重入力をなくしたい。
であれば、目的が明確です。
一方、
ECサイトと基幹システムをAPI連携したい。
だけでは、何のための連携なのかが分かりません。
同じ注文情報を扱う場合でも、
担当者の入力作業を減らしたい
在庫数を合わせたい
売上集計へ利用したい
出荷システムへ情報を渡したい
では、必要な処理が異なります。
まずは、「連携によって今の業務をどう変えたいのか」を一文で説明できる状態にしておくと、その後の話が進めやすくなります。
2. どのシステムと、どのサービスをつなぐのか
次に、連携に関係するシステムを整理します。
たとえば、
自社販売管理システム → 外部配送サービス
という構成もあれば、
ECサイト → 自社基幹システム → 外部配送サービス
のように、複数のシステムが関係する場合もあります。
「外部サービスへデータを送りたい」という要望でも、元となるデータがどこにあるのかによって、改修対象は変わります。
詳しい構成図がなくても、
システム名
何に使っているシステムか
現在の開発・保守会社
サーバーやクラウドの管理者
などが分かれば、最初の相談材料になります。
3. 何のデータを連携するのか
最初から「JSONのこの項目をこのフィールドへ」といった技術仕様まで決める必要はありません。
まずは業務上の言葉で、
顧客情報
注文情報
商品情報
在庫情報
予約情報
決済結果
配送状況
など、何を連携したいのかを整理します。
可能であれば、
顧客情報のうち、氏名・メールアドレス・電話番号を連携したい
というところまで分かると、さらに調査しやすくなります。
ここで重要なのが、双方のシステムで同じ情報を同じ方法で識別しているとは限らないことです。
たとえば、
自社システムでは「顧客番号」で顧客を管理している
外部サービスでは「メールアドレス」で利用者を識別している
という場合があります。
このとき、「自社の顧客A」と「外部サービスの利用者A」を何によって同一人物と判断するのかを決めなければなりません。
こうしたデータを対応付けるための判断キーは、API連携の設計で重要になります。
4. データをどちらからどちらへ送るのか
API連携というと「システム同士をつなぐ」と表現されますが、実際にはデータの流れる方向を考える必要があります。
たとえば、
一方向
自社システム → 外部サービス
なのか、
逆方向
外部サービス → 自社システム
なのか、
双方向
自社システム ⇄ 外部サービス
なのかで、設計は変わります。
特に双方向連携では、
両方のシステムで同じ顧客情報を変更した場合、どちらを正しい情報とするのか
という問題が出てきます。
そのため、データによっては、
「どのシステムを正とするのか」
まで整理できると、後の設計が進めやすくなります。
5. いつ・どのくらいの速さで反映したいのか
API連携では、データを反映するタイミングも重要です。
操作直後に反映したい
数分以内ならよい
1時間ごとでよい
夜間に1回まとめて連携すればよい
では、必要な仕組みが変わります。
すべてをリアルタイムにする必要はありません。
業務上、翌朝までに反映されればよいデータであれば、一定間隔でまとめて処理する方式が適している場合もあります。
一方、
決済が完了したら、すぐにサービスを利用可能にしたい
という場合には、反映時間そのものが重要な要件になります。
まずは技術方式ではなく、業務としてどのくらいの時間なら許容できるのかを整理しておくことが重要です。
6. 連携に失敗したとき、業務としてどうしたいのか
API連携では、正常に動く場合だけでなく、失敗した場合も考える必要があります。
たとえば注文情報の連携に失敗した場合、
自動的に再送する
担当者へ通知する
管理画面から再実行する
エラー状態として保存して後で確認する
といった方法があります。
どれが適切かは、業務によって異なります。
売上集計用のデータであれば多少遅れても問題ないかもしれません。
一方、商品の出荷指示であれば、長時間連携できないことで実際の業務が止まる可能性があります。
発注側で技術的なエラー処理まで決める必要はありません。
まず、
「この連携が止まったら誰が困るのか」「どのくらいの時間なら待てるのか」
を開発会社へ伝えることが重要です。
7. 外部サービスの契約・API資料を確認できるか
外部サービスについては、
APIの公式ドキュメント
利用中または契約予定のプラン
APIを利用できる契約になっているか
管理画面へアクセスできる担当者
テスト環境の有無
外部サービスの問い合わせ窓口
などを確認します。
API資料を発注側で読み解く必要はありません。
資料のURLやファイルを開発会社へ共有できれば、技術的な調査は開発側で進められます。
一方、利用できるAPIや機能が契約プランによって異なる場合もあるため、技術資料と契約状況の両方を確認できることが重要です。
また、APIキーやパスワードなどの認証情報を、初回相談時にメールなどで安易に送る必要はありません。
実際に開発で必要になった段階で、安全な受け渡し方法を開発会社と相談してください。
外部サービスの仕様によって、開発量や見積が変わることがある
事業会社側で整理した業務要件を実現できるかどうかは、最終的には外部サービス側のAPI仕様も確認する必要があります。
プレイリーソリューションズが顧客案件で外部APIの切替を調査・実装した際にも、事前の仕様確認によって開発方法へ影響する条件が見つかりました。
たとえば、APIを呼び出せる接続元のIPアドレスが制限されており、どのサーバーからAPIへ接続するのかを先に整理する必要があったケースがあります。
「APIを利用できる契約だから、どこからでも呼び出せる」とは限りません。
また、取得したい分析データについて、処理直後ではなく一定の時間差をもって反映される仕様になっているケースもありました。
この場合、「操作した直後に最新情報を表示したい」という業務要件であれば、APIの仕様との調整が必要になります。
さらに、当時確認した範囲では、必要な状態変化を通知してくれるWebhookが見当たらず、システム側から定期的にAPIへ問い合わせて状態を確認する方式を検討したケースもあります。
Webhookで通知を受け取れる場合と、一定間隔でAPIへ問い合わせる場合では、必要な処理や状態管理が異なります。
つまり外部APIの仕様は、単なる技術上の違いではなく、開発範囲や見積にも影響する条件です。
そのため、発注前には業務要件を整理し、その後に開発会社がAPI仕様を確認する、という順序で進めると整理しやすくなります。
API仕様書は「何ができるか」、発注側が整理するのは「どう使いたいか」
APIの公式ドキュメントが揃っていれば、技術調査は進めやすくなります。
ただし、API仕様書が説明しているのは、主に
「その外部サービスでは何ができるのか」
です。
開発会社が実際の連携を設計するためには、それとは別に、
「その機能を、自社業務の中でどう使いたいのか」
という情報が必要です。
この2つを分けて考えることが重要です。
発注側は業務上の目的や条件を整理し、APIでどのように実現するかは開発会社と一緒に確認する。
その役割分担にすると、発注側が最初からAPIの技術仕様をすべて理解する必要はありません。
認証方式やエラー処理など、開発会社へAPI連携部分を依頼するときの技術側の確認項目については、関連記事「API連携開発を外注するときに確認すべきポイント」で詳しく解説しています。
具体例：注文情報を外部サービスへ連携する場合
たとえば、自社の販売管理システムから配送サービスへ注文情報を連携するとします。
「注文APIを使って連携したい」だけでは、まだ開発範囲を決めるための情報として十分ではありません。
次のように整理すると、開発会社との相談が進めやすくなります。
確認項目 | 整理例 |
目的 | 配送サービスへの手入力をなくす |
目的元 | 自社販売管理システム |
連携先 | 外部配送サービス |
データ | 注文番号、氏名、住所、商品、数量 |
方向 | 自社 → 配送サービス |
タイミング | 注文確定後、数分以内 |
エラー時 | 管理担当者へ通知し、再送可能にする |
更新時 | 出荷前の住所変更は再連携する |
API資料 | 外部サービスの公式ドキュメントあり |
この状態であれば、開発会社側でAPI仕様と既存システムを確認し、
必要なAPIが利用できるか
既存システムのどこを変更するか
データの変換が必要か
エラー管理をどう実装するか
追加調査が必要な箇所はどこか
を具体化できます。
つまり、発注前に必要なのは詳細な技術設計ではなく、業務上の連携条件を説明できる状態にすることです。
プレイリーソリューションズでは、API仕様の調査から相談できます
バックエンド開発に特化したシステム開発会社 プレイリーソリューションズ合同会社では、自社システムと外部サービスのAPI連携について、要件整理・API仕様調査の段階からご相談いただけます。
発注側で認証方式やデータ形式などの技術仕様まで決めていただく必要はありません。
まず、
何を実現したいのか
どのシステムをつなぎたいのか
何のデータを扱いたいのか
いつ反映したいのか
エラー時に業務上どうしたいのか
を確認します。
そのうえで、外部サービスのAPI仕様と既存システムを調査し、
業務要件の整理 → API仕様調査 → 連携方式・影響範囲の整理 → 設計・実装・試験
と段階を分けて進めることも可能です。
Java / AWSを中心としたバックエンド開発に加え、外部API連携、GMOペイメントゲートウェイなどの決済連携、既存Webシステムへの機能追加などに対応しています。
まとめ：技術仕様より先に「業務としてどうつなぎたいか」を整理する
API連携を外部の開発会社へ依頼するとき、発注側がAPIの技術仕様をすべて理解する必要はありません。
まず整理したいのは、
何のために、どのデータを、どちらへ、いつ連携したいのか。
そして、
連携に失敗したとき、業務としてどうしたいのか。
という情報です。
そこまで整理できれば、開発会社側で外部サービスのAPI仕様を調査し、実現方法や必要な改修範囲を具体化できます。
「外部サービスにAPIはあるが、自社システムとどう連携すればよいか分からない」「何を整理してから開発会社へ相談すればよいか分からない」という場合は、プレイリーソリューションズへご相談ください。
API仕様の調査から、既存システムの影響範囲整理、設計・実装・試験まで対応しています。
