以下の資料は、要件（片方向 / 名刺→Vtiger、新規＝Leads追加、更新＝Accounts & Contacts更新、名寄せキー＝メール）に合わせて、Sansan × Vtiger OSS(v8) の連携設計をまとめました。
目次
1) 前提：両APIの特徴
Sansan 側
- API Key 認証（ユーザーごとに発行、参照権限範囲内のデータを取得） (jp-help.sansan.com)
- 名刺検索／人物情報取得／タグ取得などが可能 (docs.ap.sansan.com)
Vtiger OSS(v8) 側
webservice.phpの REST(Webservices) を使い、create/retrieve/update/query/syncなどで操作 (community.vtiger.com)- 連携実装の基本は「retrieve → 差分反映 → update」が安全（空更新事故を避ける） (Stack Overflow)
2) 連携の全体アーキテクチャ（おすすめ）
バッチ同期（定期）が最も堅いです（片方向なのでなおさら）。
(1) Sansan API から「新規/更新」候補を取得
(2) 連携アプリで正規化・名寄せ（メール）
(3) Vtiger Webservice へ反映
- 新規 → Leads に create
- 更新 → Contacts を update、関連する Accounts も update
(4) 同期カーソル（最終取得時刻 or Sansan側更新キー）を保存3) 名寄せルール（メール基準）と例外処理
基本ルール（強制）
- メールが1つでも取得できたら、それを主キーとして扱う
- Contacts 検索：
Contacts.email = メール - 見つかれば「更新フロー」
- 見つからなければ「新規フロー（Lead作成）」へ
例外（実務で必ず出ます）
- メールが空（名刺にメールが無い）
- “名寄せ不可”として リストに隔離（手動確認 or 補助キーで暫定マッチ）
- 補助キー候補：電話、会社名＋氏名（ただし誤マッチリスク増）
- 同一メールが複数Contactsに存在
- 同期停止して例外キューへ（どれを正にするかルールが必要）