外部連携API（GraphQL）設定ガイド

概要

DRIVE SFA は外部システム向けに GraphQL API を提供しています。取引先・取引先担当者・案件・営業活動のデータを外部プログラムから読み取り・書き込みすることができます。

項目	内容
エンドポイント	https://api.drivesfa.biz/graphql
プロトコル	GraphQL over HTTP（POST）
認証方式	PAT（Personal Access Token）
レート制限	1,000リクエスト / 時間 / PAT

---

このAPIでできること

操作	取引先	取引先担当者	案件	営業活動
一覧取得・検索	✅	✅	✅	✅
詳細取得	✅	✅	✅	—
新規作成	✅	✅	✅	✅
更新	✅	✅	✅	—
削除（論理）	✅	✅	✅	—

---

活用事例

📥 他システムからDRIVE SFAへデータを取り込む

• 名刺管理サービス：名刺読み取り後に取引先・担当者を自動登録
• MAツール連携：フォーム入力された見込み客を取引先担当者として登録し、案件を自動生成
• CTIシステム連携：通話終了後に createActivity(type: CALL) で電話活動を自動記録

📤 DRIVE SFAのデータを外部システムへ連携する

• 社内BI / レポートツール連携：案件・営業活動データを定期的に取得してダッシュボードに反映
• 基幹システム同期：成約した案件（contractStatusId: 1）を取得して成約処理へ連携
• SFAデータ一括エクスポート：updatedSince で差分取得してデータウェアハウスへ同期

🔄 双方向連携

• CRM / ERPとの双方向同期：externalId（外部連携ID）フィールドを利用して各システム間でレコードを関連付け

---

サービスアカウントを作成する

APIを利用するには、まずサービスアカウント（外部システム用のアカウント）を作成します。

1. 設定 → 「その他設定」 → 「サービスアカウント設定」
2. 「+ 新規作成」
3. 各項目を入力して 「保存」

設定項目	必須	説明
サービスアカウント名	✅	用途がわかる名前（例：「CRM連携用」）
説明	—	用途・担当チームなどのメモ
権限セット	✅	必要最小限の権限を付与（「閲覧のみ」を推奨）
所属組織	✅	アクセスできるデータ範囲を組織スコープで制限

---

PAT（パーソナルアクセストークン）を発行する

1. サービスアカウント詳細 → 「PAT管理」
2. 「+ トークンを発行」
3. トークンの説明・有効期限を設定して 「発行」

---

認証

発行したPATを Authorization ヘッダーに付与して POST リクエストを送信します。

curl -X POST https://api.drivesfa.biz/graphql \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ accounts(first: 10) { edges { node { id name } } } }"}'

項目	内容
ヘッダー名	Authorization
形式	Bearer <token>
有効期限	PAT発行時に設定（未設定の場合は無期限）

---

ページネーション

一覧取得クエリはすべてカーソルベースのページネーション（Relay Cursor Connections）を採用しています。

引数	型	説明
first	Int	先頭からn件取得（最大100、デフォルト10）
after	String	first と組み合わせる開始カーソル
last	Int	末尾からn件取得（最大100、デフォルト10）
before	String	last と組み合わせる終了カーソル

---

Query（データ取得）

accounts — 取引先一覧を取得

絞り込み引数

引数	型	説明
name	String	取引先名（部分一致）
externalId	String	外部連携ID（完全一致）
updatedSince	String	指定日時以降に更新されたもの（ISO8601形式）
first / after / last / before	—	ページネーション引数

レスポンスフィールド

フィールド	説明
id	取引先ID
name / nameKana	会社名 / フリガナ
tel / email / webSite	電話番号 / メール / Webサイト
zipCode / prefectureKindId / city / address	住所情報
representativeContact	代表担当者名
externalId	外部連携ID
createdAt / updatedAt / lastActionDate	日時情報
properties	カスタム項目（name / value）
contacts / deals / activities	関連データ（ページネーション対応）

{
  accounts(name: "株式会社", updatedSince: "2026-01-01T00:00:00", first: 20) {
    edges {
      cursor
      node {
        id
        name
        externalId
        updatedAt
        contacts(first: 5) { edges { node { id name } } }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

---

account — 取引先の詳細を取得

引数	型	必須	説明
id	String	✅	取引先ID

{ account(id: "123") { id name tel email webSite properties { name value } } }

---

contacts — 取引先担当者の一覧を取得

絞り込み引数

引数	型	説明
accountId	String	取引先IDで絞り込み
email	String	メールアドレス（部分一致）
externalId	String	外部連携ID（完全一致）
first / after / last / before	—	ページネーション引数

レスポンスフィールド

フィールド	説明
id	担当者ID
accountId	所属する取引先ID
name / nameKana	氏名 / フリガナ
department / position	部署 / 役職
phoneNumber / email	電話番号 / メール
isKeyPerson	キーパーソンフラグ
externalId	外部連携ID
properties	カスタム項目

{
  contacts(accountId: "123", first: 10) {
    edges { node { id name email department position externalId } }
    pageInfo { hasNextPage endCursor }
  }
}

---

contact — 取引先担当者の詳細を取得

引数	型	必須	説明
id	String	✅	担当者ID

{ contact(id: "456") { id name email department position isKeyPerson } }

---

deals — 案件の一覧を取得

絞り込み引数

引数	型	説明
accountId	String	取引先IDで絞り込み
stage	Long	契約ステータスID（1: 成約 / 2: 失注 / 3: 進行中）
ownerUserId	Long	担当ユーザーIDで絞り込み
updatedSince	String	指定日時以降に更新されたもの（ISO8601形式）
externalId	String	外部連携ID（完全一致）
first / after / last / before	—	ページネーション引数

レスポンスフィールド

フィールド	説明
id	案件ID
accountId	取引先ID
name	案件名
estimatedAmount	売上見込金額
startDate / scheduledDate	開始日 / 案件完了予定日
contractStatusKey	契約ステータスキー（進行中 / 成約 / 失注）
contractSignedDate	成約日
projectFlowName / projectStepName	案件フロー名 / ステップ名
externalId	外部連携ID
properties	カスタム項目
activities	関連する営業活動（ページネーション対応）

{
  deals(stage: 1, updatedSince: "2026-01-01T00:00:00", first: 50) {
    edges {
      node {
        id name accountId estimatedAmount contractStatusKey scheduledDate externalId
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

---

deal — 案件の詳細を取得

引数	型	必須	説明
id	String	✅	案件ID

{ deal(id: "789") { id name estimatedAmount contractStatusKey scheduledDate } }

---

activities — 営業活動の一覧を取得

絞り込み引数

引数	型	説明
accountId	String	取引先IDで絞り込み
dealId	String	案件IDで絞り込み
type	ActivityType	活動タイプで絞り込み（下記参照）
since	String	指定日時以降の活動（ISO8601形式）
first / after / last / before	—	ページネーション引数

レスポンスフィールド

フィールド	説明
id	活動ID
type	活動タイプ（ActivityType）
accountId / dealId / contactId	関連先ID
occurredAt	活動発生日時
summary / detail	概要 / 詳細
properties	カスタム項目

ActivityType の値

値	説明
MEETING	会議
NEGOTIATION	商談
CALL	電話
EMAIL	メール
OTHER	その他（タスク等）

{
  activities(accountId: "123", type: CALL, since: "2026-01-01T00:00:00", first: 20) {
    edges { node { id type occurredAt summary dealId } }
    pageInfo { hasNextPage endCursor }
  }
}

---

Mutation（データ書き込み）

createAccount — 取引先を作成

フィールド	型	必須	説明
name	String	✅	会社名
nameKana	String	—	フリガナ
tel	String	—	電話番号
email	String	—	メールアドレス
representativeContact	String	—	代表担当者名
webSite	String	—	WebサイトURL
zipCode	String	—	郵便番号
prefectureKindId	Long	—	都道府県ID
city / address	String	—	市区町村 / 番地
properties	[PropertyInput]	—	カスタム項目

mutation {
  createAccount(input: {
    name: "株式会社サンプル"
    tel: "03-0000-0000"
    webSite: "https://example.com"
    externalId: "crm-account-001"
  }) {
    id name createdAt
  }
}

---

updateAccount — 取引先を更新

フィールド	型	必須	説明
id	String	✅	更新する取引先ID
その他フィールド	—	—	未指定の場合は既存値を維持

mutation {
  updateAccount(input: { id: "123", tel: "03-1111-1111" }) { id name tel }
}

---

deleteAccount — 取引先を削除（論理削除）

引数	型	必須	説明
id	String	✅	削除する取引先ID

mutation { deleteAccount(id: "123") }  # 削除された取引先IDが返される

---

createContact — 取引先担当者を作成

フィールド	型	必須	説明
accountId	String	✅	所属させる取引先ID
name	String	✅	氏名
nameKana	String	—	フリガナ
department / position	String	—	部署 / 役職
phoneNumber / email	String	—	電話番号 / メール
dateOfBirth	String	—	生年月日（ISO8601形式）
isKeyPerson	Boolean	—	キーパーソンフラグ
note	String	—	備考
properties	[PropertyInput]	—	カスタム項目

mutation {
  createContact(input: {
    accountId: "123"
    name: "田中 太郎"
    email: "tanaka@example.com"
    position: "部長"
  }) {
    id name email
  }
}

---

updateContact — 取引先担当者を更新

フィールド	型	必須	説明
id	String	✅	更新する担当者ID
その他フィールド	—	—	未指定の場合は既存値を維持

mutation {
  updateContact(input: { id: "456", position: "本部長" }) { id name position }
}

---

deleteContact — 取引先担当者を削除（論理削除）

mutation { deleteContact(id: "456") }

---

createDeal — 案件を作成

フィールド	型	必須	説明
accountId	String	✅	取引先ID
name	String	✅	案件名
projectFlowName	String	✅	案件フロー名
projectStepName	String	—	案件ステップ名
contractStatusKey	String	—	契約ステータスキー（成約 / 失注 / 進行中）
estimatedAmount	Long	—	売上見込金額
startDate / scheduledDate	String	—	開始日 / 案件完了予定日（ISO8601形式）
note	String	—	備考
userIds	[Long]	—	担当ユーザーIDリスト
contactIds	[Long]	—	関連担当者IDリスト
productIds	[Long]	—	商品IDリスト
properties	[PropertyInput]	—	カスタム項目

mutation {
  createDeal(input: {
    accountId: "123"
    name: "DRIVE SFA 導入提案"
    projectFlowName: "標準フロー"
    projectStepName: "提案"
    contractStatusKey: "進行中"
    estimatedAmount: 500000
    scheduledDate: "2026-06-30"
  }) {
    id name contractStatusKey
  }
}

---

updateDeal — 案件を更新

フィールド	型	必須	説明
id	String	✅	更新する案件ID
その他フィールド	—	—	未指定の場合は既存値を維持

mutation {
  updateDeal(input: { id: "789", contractStatusKey: "成約", contractSignedDate: "2026-03-11" }) {
    id name contractStatusKey
  }
}

---

deleteDeal — 案件を削除（論理削除）

mutation { deleteDeal(id: "789") }

---

createActivity — 営業活動を作成

フィールド	型	必須	説明
accountId	String	✅	取引先ID
type	ActivityType	✅	活動タイプ（MEETING / NEGOTIATION / CALL / EMAIL / OTHER）
occurredAt	String	✅	活動発生日時（ISO8601形式）
idempotencyKey	String	✅	重複登録防止キー（同一キーで再送した場合は既存を返す）
dealId	String	—	案件ID
contactId	String	—	担当者ID
summary	String	—	概要
detail	String	—	詳細
properties	[PropertyInput]	—	カスタム項目

mutation {
  createActivity(input: {
    accountId: "123"
    type: CALL
    occurredAt: "2026-03-11T10:00:00"
    idempotencyKey: "cti-call-20260311-001"
    dealId: "789"
    summary: "初回ヒアリング電話"
  }) {
    id type occurredAt summary
  }
}

---

カスタム項目（PropertyInput）

各 Mutation の properties 引数でカスタム項目の値を設定・更新できます。

フィールド	型	必須	説明
name	String	✅	カスタム項目の物理名
value	String	—	設定する値

物理名の確認方法：設定 → カスタム項目設定 → 対象の項目の「物理名」列を参照してください。

mutation {
  updateAccount(input: {
    id: "123"
    properties: [
      { name: "industry", value: "製造業" },
      { name: "annual_revenue", value: "1000000000" }
    ]
  }) { id }
}

---

レート制限

PATごとに 1,000リクエスト / 時間 の上限が設定されています。各レスポンスのヘッダーで現在の残数を確認できます。

ヘッダー	内容
X-RateLimit-Limit	上限リクエスト数（1000）
X-RateLimit-Remaining	残りリクエスト数
X-RateLimit-Reset	制限リセット時刻（UNIXタイムスタンプ）
Retry-After	次にリクエスト可能になるまでの秒数（超過時のみ）

---

関連記事

• 権限セットの設定
• データの参照スコープ