CRM外部ID・Upsertキーの設計｜CSV・API連携で重複レコードを作らない方法

CSVを取り込むたびに同じ会社や担当者が増える、API再送後に更新対象がずれる、連携元のIDを変更したら過去データと結び付かなくなる。このような重複は、CRMの名寄せ機能だけでなく、連携元とCRMの間で「同じレコード」を指すキーが定まっていないことから起こります。会社名、メールアドレス、電話番号のように変わり得る値をそのまま照合キーにすると、表記修正や組織変更が更新ではなく新規作成として扱われます。

外部IDは、連携元が管理する識別子をCRM側の項目へ保持し、次回以降も同じレコードを特定するための値です。Upsertは、そのキーに一致するレコードがあれば更新し、なければ作成する処理です。ただし、キーが不変で一意であること、空値や重複を拒否できること、再送時に同じ処理結果へ着地すること、キー変更時の対応表を残すことまで揃わなければ安全には使えません。顧客項目の全体設計は顧客データ設計の基本ルール、既に発生した重複の判定はCRMの名寄せルールと分けて考えます。

CRMの外部ID・Upsertキーは、連携元が発行し、業務上の名称や担当変更で変わらない値を使うのが基本です。CRM内部IDはCRM内の参照に残し、外部連携では「連携元システム＋外部ID」の対応を記録します。取込前に一意性、空値、文字正規化を検証し、Upsert後は作成・更新・失敗を件数とキー単位で照合すると、再実行による重複を防げます。

---

本記事のポイント

1. 外部IDは連携元が発行する不変・一意な値を使い、会社名やメールアドレスなど変更される業務値を単独キーにしません。
2. Upsert前後で入力件数、作成、更新、失敗、未処理を照合し、同じ入力を再送しても同じレコードへ着地するか確認します。
3. キー変更やシステム統合では旧キーを上書きせず、新旧対応表、適用日、移行状態、切り戻し条件を保持します。

---

外部IDとCRM内部IDの役割を分ける

CRM内部IDは、CRMがレコード作成時に発行する主キーです。CRM内の関連付けや画面遷移では確実に使えますが、連携元がその値を知らない初回取込や、CRMを移行した後の照合にはそのまま使えません。外部IDはこの境界を埋め、受注管理、基幹システム、問い合わせフォーム、データウェアハウスなどのレコードをCRMの同一レコードへ結び付けます。

最初に決めるべきなのは「どのシステムがそのキーを発行し、誰が変更を承認するか」です。顧客の正本が基幹システムなら基幹側の顧客番号、問い合わせの正本が受付システムなら受付IDを使います。複数の連携元が独自IDを持つ場合は、一つの外部ID欄へ混在させず、システム別の外部ID項目か、別の対応テーブルに分けます。

候補	向いている用途	主なリスク	設計判断
連携元の不変ID	同じ連携元からの継続取込	システム統合・再構築で値が変わる場合がある	発行元名とセットで保持し、変更時の対応表を用意する
CRM内部ID	CRM内の関連付け、CRMからの更新	初回取込では連携元が知らず、CRM移行で変わる	外部連携の唯一の照合キーにはしない
メールアドレス・電話番号	補助照合、候補提示	変更、共有、再利用、表記差がある	単独の恒久キーではなく名寄せ候補に使う
会社名・氏名	人による確認、検索	法人格、表記、組織変更、同名がある	正規化しても一意キーにはしない
複合キー	単一の不変IDがない既存システム	構成項目の一つが変わると別レコードになる	構成、順序、正規化、変更条件を固定する

外部IDと名寄せは目的が異なります。外部IDは「同じ連携元の同じレコード」を機械的に再識別する仕組みで、名寄せは複数の発生源から来たレコードが同一人物・同一法人かを判断する処理です。外部IDが一致しないデータを会社名だけで自動統合すると誤結合の危険があります。スプレッドシート段階で重複が生まれる原因は顧客管理の重複を発生源から減らす設計も参考になります。

不変性・一意性・再送可能性でキーを設計する

外部IDは短く見えるほど良いわけではありません。判断基準は、業務名ではなく機械的な性質です。少なくとも、発行元の中で一意、レコードの存続期間中に不変、空値を許さない、大文字小文字や前後空白の扱いが決まっている、再利用しない、削除・統合後の履歴を追える、という条件を確認します。

• 発行元を識別する。同じ「12345」でも販売管理とサポート管理では別の値です。項目を分けるか、名前空間を持つ対応テーブルで区別します。
• 表示値と照合値を分ける。顧客番号にハイフンを表示する場合でも、照合前に削除するのか保持するのかを固定し、処理ごとに変えません。
• 空値を作成キーにしない。外部IDが空の行は自動作成せず、隔離して発行元へ戻すか、承認された一時IDを発行します。
• 重複を取込前に止める。一つのファイル内、CRM既存値、並行実行中の入力の三つで重複を確認します。
• 失効と統合を履歴化する。旧キーを別顧客へ再利用せず、統合先の内部IDと新しい外部IDを対応表へ残します。

Upsertは重複を自動的に直す機能ではありません。間違ったキーが一意なら、間違ったレコードを一貫して更新してしまいます。キーに何を入れるか、どの列を更新対象にするか、空値で既存値を消してよいかを分けて決めます。特にCSVでは、列が空であることが「変更なし」なのか「値を削除」なのかを取込仕様へ明記します。

Salesforce・Dataverse・HubSpotの違いを確認する

製品ごとに名称や制約は違いますが、いずれも「内部ID以外の一意な値でレコードを特定する」という考え方を持っています。設定前に、対象オブジェクト、キーの型、複合キーの可否、一意性の反映時期、APIの作成・更新判定、失敗時の応答を公式仕様で確認します。

製品	識別の仕組み	Upsertで見る点	運用上の注意
Salesforce	External IDとして設定した項目	指定した外部IDの存在に応じて作成または更新	オブジェクト、外部ID項目、値の組み合わせを連携仕様に固定する
Microsoft Dataverse	業務列または複数列で定義する代替キー	主キーまたは代替キーで既存行を探索して作成・更新	キー用インデックスの作成状態と、キー値に使えない文字・テーブル種別を確認する
HubSpot	一意値を要求するカスタムプロパティ	一意プロパティ名をidPropertyとして値を指定する	対象オブジェクトの一意プロパティ数やAPIバージョンの最新条件を確認する

Salesforceの公式Upsert資料は、外部ID項目に指定値が存在するかによってレコードを挿入または更新すると説明しています。Dataverseの代替キーは、外部データストアの識別子に対応する業務列や列の組み合わせで行を一意に識別でき、データ統合で使えます。代替キーのインデックス作成は非同期のため、設定直後に大量取込へ進まず状態を確認します。

Dataverseの公式資料は、既存有無が分からないデータ統合でUpsertにより事前照会を減らせる一方、レコードが存在しないと分かっている場合はCreateより性能上の負担があるとしています。HubSpotの公式プロパティ資料では、一意値プロパティを作成して内部IDと同様にレコード特定へ使えます。最新仕様ではオブジェクトごとに一意IDプロパティ数の上限もあるため、連携ごとに無計画に増やさず、共通キーと用途別キーを整理します。

7ステップでCSV・API連携を導入する

1. 発生源と正本を一覧にする。連携元、対象オブジェクト、発行するID、更新責任者、送信頻度、削除・統合の通知方法を記録します。フォーム、CSV、API、手動入力を別経路として棚卸しします。
2. 既存データを検査する。候補キーの空値、重複、形式違い、同じキーで属性が競合する件数を集計します。CRM側の内部IDと候補外部IDの対応表を変更前に保存します。
3. キーと正規化を決める。発行元、型、最大長、大文字小文字、前後空白、ゼロ埋め、記号、複合順序、再利用禁止、空値時の扱いを仕様化します。
4. 更新可能な項目を限定する。連携元が正本である項目だけを更新し、CRM担当者が管理するメモやステータスをCSV空値で消さないよう項目別の所有権を決めます。API経由の操作範囲はAPI・MCPから操作するCRMの設計も確認します。
5. 小さな件数で作成・更新・失敗を試す。新規キー、既存キー、空値、重複、形式不正、削除済みキー、統合済みキーを含むテストデータを使い、期待する内部IDへ着地するか確認します。
6. 同じ入力を再送する。初回成功後に同じファイルやイベントを再実行し、新規作成件数が増えず、同じ内部IDが更新されることを確認します。タイムアウト後の再送も試します。
7. 本番結果を照合して固定する。入力、作成、更新、失敗、未処理の合計を一致させ、外部IDと内部IDの対応、エラー理由、再処理回数を保存します。差があれば次のバッチへ進みません。

外部IDの設計が完了するのは、キーを一意にした時ではなく、同じ入力を再送しても同じCRMレコードへ着地し、キー変更と失敗理由を追跡できる時です。

CRM移行と同時に外部IDを付け替える場合は、旧CRM内部ID、旧外部ID、新外部ID、新CRM内部IDを同じ対応表で管理します。移行全体の切り分けはCRM乗り換えの失敗を防ぐチェックリストを使い、キー変換と項目変換を別の検証単位にします。

失敗・再送・キー変更を監視する

APIがタイムアウトしたとき、送信側には失敗に見えてもCRM側では作成済みのことがあります。この状態で新しいキーを発行して再送すると重複します。再送には同じ外部IDを使い、可能なら連携イベントIDも保持して、処理済みか照会できるようにします。応答を受け取れなかった行だけを無条件に新規作成へ回しません。

監視項目	異常の例	停止・確認条件
入力件数と処理結果	作成＋更新＋失敗＋未処理が入力件数と合わない	次回実行を止め、欠落したキーを特定する
新規作成率	通常より急増する	照合項目名、正規化、発行元、空値を確認する
一意性エラー	同じ外部IDが複数行・複数レコードにある	自動統合せず、発行元と既存対応表を確認する
更新対象の偏り	一つのキーへ多数の入力が集中する	複合キーの欠落や固定値の誤設定を疑う
再処理回数	同じ行が繰り返し失敗する	回数上限で隔離し、人が原因を確認する
キー変更件数	承認なしに旧キーが消える	新旧対応表と適用日がなければ反映しない

キーを変更するときは、既存の外部ID欄を一括上書きして終わらせません。まず新しいキーを別項目へ追加し、旧キーと新キーの対応、対象内部ID、変換理由、移行状態を記録します。新旧のどちらで照会しても同じレコードへ着地する並行期間を設け、送信元を順に切り替えます。監視期間後に旧キーを読取専用または履歴へ移し、削除する場合も証跡を残します。

複数レコードを統合する場合は、残すCRM内部IDを先に決め、廃止する外部IDを別顧客へ再利用しません。統合前後の関連データ、活動、商談、同意状態への影響も確認します。外部IDが正しくても、更新対象項目の所有権や統合先が誤っていればデータは壊れるためです。

よくある質問

CRMの外部IDはどのシステムの値を使いますか？

そのレコードの正本となる連携元が発行し、業務上の名称変更や担当変更で変わらない値を使います。複数システムが独自IDを持つ場合は、発行元別の項目または対応テーブルへ分け、値だけを一つの欄へ混在させません。

External IDとCRM内部IDはどう使い分けますか？

CRM内部IDはCRM内の関連付けやCRM起点の更新に使い、外部IDは連携元のレコードをCRMの同一レコードへ再識別するために使います。対応表には両方を保持し、CRM移行や統合時に追跡できるようにします。

Upsertの再実行で重複作成を防ぐには何を確認しますか？

同じ外部ID、同じ正規化、同じ対象オブジェクトで再送し、初回と同じCRM内部IDが更新されることを確認します。応答不明の行へ新しいキーを発行せず、作成・更新・失敗・未処理の合計を入力件数と照合します。

外部キーを変更・統合するときにどう移行しますか？

旧キーを上書きせず、新キーを別項目へ追加して新旧対応表を作ります。並行照会、送信元の段階切替、影響監視、切り戻しを行い、旧キーを別顧客へ再利用しません。

メールアドレスを外部IDにしてもよいですか？

補助照合には使えますが、退職、改姓、ドメイン変更、共有アドレス、再利用があるため、個人を長期に識別する唯一の外部IDには向きません。発行元の不変IDを主キーにし、メールアドレスは変更履歴を持つ属性として扱います。

複合キーを使うときの注意点は何ですか？

構成列の順序、区切り、空値、大文字小文字、前後空白、ゼロ埋めを固定します。一つの構成値が変わると別レコードとして判定されるため、変更される業務値を含める場合は新旧対応と移行手順が必要です。

外部IDは、重複を見つけた後に掃除するための項目ではなく、同じ入力を同じレコードへ安全に届けるための契約です。発行元、不変性、一意性、正規化、再送、キー変更、結果照合を一つの運用として固定すれば、CSVとAPIのどちらでも重複作成や誤更新を減らせます。