連携は、コードを書く前に9割決まる

複数の外部システムをCRMにつなぐ案件では、最初にAPIの仕様書を開いてコードを書き始めたくなります。しかし、これが一番多い失敗パターンです。認証は通ってデータも流れるのに、後から「このレコードは誰が最後に更新したのか分からない」「同じ会社が重複して登録される」といった問題が出てきて、結局作り直すことになります。

性質の異なる複数の外部システム——チャットツールの投稿、スプレッドシートの台帳、別の業務システムが持つ顧客ID——をCRMに接続する実装を担当してきた中で、うまくいく案件には共通して、コードを書く前に固めた3つの設計がありました。

最初に決めるのは、外部システムのデータとCRMオブジェクトの対応関係です。特に重要なのが「突合キー」——外部システム側のIDとCRM側のレコードを、重複なく一意に結びつける項目——をどこに置くかです。ここを後回しにすると、同じ会社・同じ顧客が何重にも登録される事故が起きます。

実際に、性質の異なる3つの外部システム（チャットツールの投稿、スプレッドシートの台帳、外部の顧客IDマスター）をCRMに接続する実装を一人で担当した際も、最初に固めたのはコードではなく、この対応関係の図でした。External ID（外部システム側の一意なIDを保持する専用項目）をどのオブジェクトに、どういう命名で持つかを先に決めたことで、後工程の実装がぶれませんでした。

次に、実際のデータがどう見えるかを先に確認します。スプレッドシートなら列の並び、チャットツールならメッセージの形式、外部システムならAPIレスポンスの構造。ここで「列Aは会社名、列Bは資本金」といった実物ベースのマッピング表を作っておくと、実装中に仕様が変わったときの影響範囲がすぐ分かります。

この工程を飛ばしてオブジェクト構造図から直接コードに進むと、実装の途中で「この項目、思っていた形式と違う」という手戻りが頻発します。

最後に、どう動かすかを決めます。誰が実行するのか（対話ログインが要らない専用の認証方式を選べるか）、いつ動かすのか（人の操作をきっかけに動くイベント駆動か、一定間隔で動くバッチか）、失敗したときにどう気づくか（通知先と再実行の設計）。この3つを最後に決めるからこそ、ステップ1・2で固めた構造を壊さずに実装できます。

この順序で進めた結果、性質の異なる3つの外部システムからの連携で、合計1,502件のレコード同期と、117社・135件の申請データの反映を、大きな手戻りなく実装できました。

認証方式の選び方も、この段階で具体的に詰めます。Salesforceとの連携でよく使うのはClient Credentials FlowとJWT Bearer Flowの2つです。API専用の連携ユーザーはブラウザでの対話ログインができないため、通常のWeb OAuth（ブラウザでの認可コード取得が必要な方式）は使えません。Client Credentials FlowはConsumer Key・Secretだけでトークンを取得でき、refresh tokenの失効・再認証が発生しないため無人の定期実行に向いています。JWT Bearer Flowは証明書の運用が必要になる分セットアップは重くなりますが、Client Credentials Flowが使えない古い組織設定でも動きます。「まずClient Credentials Flowを試し、組織側の制約で使えない場合だけJWT Bearer Flowに切り替える」という優先順位で選ぶと迷いません。

実行タイミングの設計も、選択肢を知っているかどうかで結果が変わります。人の操作（チャットツールへの投稿やリアクション等）をきっかけに即座に反映したいなら、Webhook・Events APIを使ったイベント駆動にします。一方、スプレッドシートの台帳のように「決まった間隔で差分を拾えれば十分」なデータは、時間主導トリガーによるバッチの方がシンプルで壊れにくく、実装・保守のコストも低く済みます。イベント駆動の方が「リアルタイムで高度」に見えますが、要件が伴わないのにイベント駆動を選ぶと、複雑さに見合う価値のないシステムになりがちです。

手戻りの性質が違う

構造の手戻り（ステップ1・2）は設計のやり直しですが、処理フローの手戻り（ステップ3）は設定変更で済むことが多い。壊れやすい方を先に固める

「動くコード」と「壊れないコード」は別物

コードは初日から動かせますが、突合キー設計を後回しにした「動くコード」は、データが増えるほど壊れやすくなります

御社で今動いている（あるいは検討中の）システム連携は、この3ステップのうちどこから始まりましたか。もしステップ3（認証・実装）から始まっているなら、一度立ち止まって、突合キーの設計だけでも先に確認する価値があります。