システム統合とAPI連携の実践

最初に決めるべきは「境界」「同期/非同期」「データの主権」

統合は実装前の合意形成が8割です。どのシステムが何を担い、どの速度で、どの正確さでつながるのか。曖昧なまま着手すると、後ろ倒しの泥沼になります。現場で使える判断軸は次の通りです。

• 境界の定義: 顧客・商品・在庫などのマスタは「主系」を一つ定め、他は参照か派生に徹する。更新は主系を起点にする。
• 同期/非同期の使い分け: 画面操作で即時性が要る処理は同期（目安P95 300ms以内）。在庫集計や会計などは非同期でピーク平準化。
• 停止時の設計: 相手が落ちたらどうするかを先に決める。キューに溜めるか、ユーザーにリトライを促すか、代替経路を用意するか。
• 運用責任: 失敗時の最終責任者（監視・連絡・復旧手順のオーナー）を統合単位で明確にする。

この三点が固まると、APIの粒度やイベントの設計、SLOの議論がぶれません。逆に曖昧だと、設計・テスト・運用すべてが不安定になります。

API連携の設計実務：壊れない契約と安全な呼び出し

仕様を「契約」に落とす

口頭の前提は必ず仕様化します。OpenAPIで入出力・エラー・ページング・フィルタを定義し、非互換はエンドポイントを分けてバージョン管理（/v2など）。フィールド追加は後方互換に配慮し、未知フィールドは無視する実装を基本にします。フロントの集約にはGraphQL、双方向ストリーミングや厳密な型はgRPC、広範な互換性ならRESTといった使い分けも有効です。

冪等性・再試行・整合性

• 書き込みAPIは冪等性キーを受け、タイムアウトや重複送信でも一度だけ反映。
• 429/503は指数バックオフで自動再試行。上限回数や総待機時間をSLOに合わせて設定。
• 分散トランザクションは避け、補償トランザクションやアウトボックス＋イベント配信で整合性を保つ。
• 業務的な可逆性を前提に、取消・再適用のパスを最初に設計する。

認証・権限・監査

• 認可はOAuth 2.0やクライアント証明書で機械間を区別。スコープで最小権限。
• テナント分離キーを必須化し、ログには個人情報を残さない。必要に応じてトークン化。
• レート制限・クオータで乱高下を抑え、同時に相手の保護にもなる。

運用を見える化する

相関IDを全レイヤーで引き回し、分散トレーシングと合成監視を常設します。典型SLOは「P95レイテンシ300ms以下」「1時間あたり失敗率0.1%以下」。デッドレタキューは手動再送の手順とセットで用意します。

実装パターンと開発のコツ

• WebhookかPollingか: 日次・時間単位の鮮度で十分ならPolling。秒単位の通知はWebhook＋署名検証。重複配信を前提に設計。
• 変換層の設置: フォーマット（JSON/CSV/XML）や通貨・単位の変換はゲートウェイで吸収。上流・下流の独立性を高める。
• コントラクトテスト: 仕様書を単なるドキュメントで終わらせず、契約テストで破壊的変更を検知。
• 段階移行: バッチからイベントへはダブルライト→リプレイ検証→段階切替。ロールバック手順を事前に演習。
• AI支援の活用: ChatGPTやClaudeでOpenAPI雛形を素早く作り、CopilotでクライアントSDKを生成、Geminiでテストデータを自動生成。機密は投入せず、レビューを前提に取り込む。

このあたりの小さな積み重ねが、可用性と変更容易性の差になります。特に「重複・遅延・順序の乱れは起こる」という前提で、設計とテストケースを用意するのが肝心です。

身近な活用例：都市部で30店舗の飲食チェーン、受発注と会計の統合

業種・規模・状況: 都市部で30店舗を展開する飲食チェーン。店舗のPOSは世代が混在、仕入はメール＋表計算、会計はクラウド。繁忙期は発注の遅延と在庫ズレが恒常化していました。

失敗の経緯: 毎夜のCSVバッチ連携で在庫と売上を突合していましたが、取引先ごとに列定義が異なり、突合エラーが週2回発生。朝の開店時に欠品が見つかり、現場が電話で調整。APIは一部導入済みでしたが、レート制限に当たると手動リトライになり、二重計上も散見されました。

改善の方針: 在庫は本部システムを主系に定義。発注は非同期イベント連携へ、会計は日次バッチを継続しつつ、価格照会と決済は同期APIに統一。冪等性キー・相関IDを必須化し、Webhookは署名検証と再送ルールを設置。仕様はOpenAPIで固定し、破壊的変更は新バージョンで段階移行。デッドレタは運用窓口で24時間以内に処置するSLOを設定しました。

移行手順: 2週間のダブルライト期間でイベントとバッチの差分を可視化し、ズレが0.5%以下になった段階で切替。ゲートウェイでフォーマット変換を集約し、店舗側改修を最小化。相関IDに基づくダッシュボードで遅延原因を即特定できるようにしました。

結果: P95の価格照会レイテンシは450ms→220ms、欠品率は3.2%→0.9%、夜間バッチの失敗は0件に。二重計上は冪等性で解消、繁忙期の電話対応は6割減。意思決定の要は「何を同期にし、何を非同期で許容するか」と「主系の一本化」でした。小さな規模でも段階移行と契約テストを組み合わせれば、運用の痛みを最小に実現できます。

受託開発ソリューション事業では、既存資産・業務制約・可用性目標を踏まえ、最小構成から始めて段階的に拡張する統合設計が要請されます。API契約、冪等性、監視、運用責任までをひとつの設計として扱うことで、導入後の現場が回り続ける統合になります。技術だけでなく、業務と運用を横断して設計・実装・定着を支えるのが、この事業区分の価値だと考えます。