外部連携API仕様（GraphQL）

概要

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

• エンドポイント：/graphql
• プロトコル：GraphQL over HTTP (POST)
• 認証：PAT（Personal Access Token）

---

このAPIでできること

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

---

活用事例

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

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

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

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

🔄 双方向連携

• CRS / ERPとの双方向同期：externalId（外部連携ID）フィールドを利用して各システム間でレコードを関連付け。DRIVE SFA側の変更と外部システム側の変更を相互に反映

認証

Personal Access Token（PAT）

GraphQL APIはサービスアカウントに発行したPATで認証します。

• リクエストヘッダーに Authorization: Bearer <token> を付与してください
• PATはサービスアカウント単位で発行・失効・削除できます
• PATには有効期限（expiresAt）を設定できます。未設定の場合は無期限です
• トークンの平文は発行時1回のみ返却されます。再表示はできません

---

レート制限

各PATにはリクエスト数の上限があります。

• 上限を超えた場合、HTTP ステータスは 200 のままですが、レスポンスボディの errors フィールドにレート制限エラーが返ります（GraphQL仕様のため）
• レスポンスヘッダーで現在の制限状況を確認できます：

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

---

ページネーション

一覧取得クエリは Relay Cursor Connections 仕様に準拠したカーソルベースのページネーションを採用しています。

引数	説明
first	前方からn件取得
after	first と組み合わせて使用するカーソル
last	後方からn件取得
before	last と組み合わせて使用するカーソル

• first と last を同時に指定することはできません
• デフォルトは 10件、最大 100件
• カーソルはレスポンスの edges[].cursor および pageInfo.startCursor / pageInfo.endCursor から取得します

---

Query（データ取得）

取引先

# 取引先一覧
query {
  accounts(
    name: String         # 取引先名（部分一致）
    externalId: String   # 外部連携ID（完全一致）
    updatedSince: String # この日時以降に更新されたもの（ISO8601形式）
    first: Int
    after: String
    last: Int
    before: String
  ) {
    edges {
      cursor
      node {
        id name nameKana tel email representativeContact
        webSite zipCode prefectureKindId city address
        externalId createdAt updatedAt lastUpdatedUserId lastActionDate
        properties { name value }
        contacts(first: Int, after: String) { edges { node { id name } } pageInfo { ... } }
        deals(first: Int, after: String) { edges { node { id name } } pageInfo { ... } }
        activities(first: Int, after: String) { edges { node { id type } } pageInfo { ... } }
      }
    }
    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
  }
}

# 取引先詳細
query {
  account(id: "123") {
    id name ...
  }
}

取引先担当者

query {
  contacts(
    accountId: String   # 取引先IDでフィルタ
    email: String       # メールアドレス（部分一致）
    externalId: String  # 外部連携ID（完全一致）
    first: Int  after: String  last: Int  before: String
  ) {
    edges {
      cursor
      node {
        id accountId name nameKana department position
        phoneNumber email dateOfBirth isKeyPerson note
        externalId createdAt updatedAt
        properties { name value }
      }
    }
    pageInfo { ... }
  }
}

query { contact(id: "456") { id name ... } }

案件

query {
  deals(
    accountId: String    # 取引先IDでフィルタ
    stage: Long          # 契約ステータスID（1:進行中 / 2:成約 / 3:失注）
    ownerUserId: Long    # 担当ユーザーIDでフィルタ
    updatedSince: String # この日時以降に更新されたもの（ISO8601形式）
    externalId: String   # 外部連携ID（完全一致）
    first: Int  after: String  last: Int  before: String
  ) {
    edges {
      cursor
      node {
        id accountId name estimatedAmount startDate scheduledDate
        contractStatusId contractSignedDate contractCanceledDate
        contractCanceledAmount contractCanceledReason
        projectFlowId projectStepId note
        externalId createdAt updatedAt lastUpdatedUserId
        properties { name value }
        activities(first: Int, after: String) { edges { node { id type } } pageInfo { ... } }
      }
    }
    pageInfo { ... }
  }
}

query { deal(id: "789") { id name ... } }

営業活動

query {
  activities(
    accountId: String   # 取引先IDでフィルタ
    dealId: String      # 案件IDでフィルタ
    type: ActivityType  # 活動タイプでフィルタ（下記参照）
    since: String       # この日時以降の活動（ISO8601形式）
    first: Int  after: String  last: Int  before: String
  ) {
    edges {
      cursor
      node {
        id type accountId dealId contactId occurredAt
        summary detail externalSystem externalId createdAt
        properties { name value }
      }
    }
    pageInfo { ... }
  }
}

---

Mutation（データ書き込み）

取引先

# 作成
mutation { createAccount(input: {
  name: String!        # 必須
  nameKana: String  tel: String  email: String
  representativeContact: String  webSite: String
  zipCode: String  prefectureKindId: Long  city: String  address: String
  properties: [PropertyInput]
}) { id name ... } }

# 更新（未指定フィールドは既存値を維持）
mutation { updateAccount(input: {
  id: String!
  name: String  nameKana: String  ...（各フィールド任意）
  properties: [PropertyInput]
}) { id name ... } }

# 削除（論理削除）
mutation { deleteAccount(id: "123") }  # 削除されたIDを返す
# ⚠️ 取引先に紐づく案件もすべて論理削除されます

取引先担当者

mutation { createContact(input: {
  accountId: String!  name: String!
  nameKana: String  department: String  position: String
  phoneNumber: String  email: String  dateOfBirth: String
  isKeyPerson: Boolean  note: String
  properties: [PropertyInput]
}) { id name ... } }

mutation { updateContact(input: { id: String!, ... }) { id name ... } }

mutation { deleteContact(id: "456") }

案件

mutation { createDeal(input: {
  accountId: String!  name: String!  projectFlowId: Long!  projectStepId: Long!
  contractStatusId: Long!  estimatedAmount: Long
  startDate: String  scheduledDate: String  note: String
  userIds: [Long]  contactIds: [Long]  productIds: [Long]
  properties: [PropertyInput]
}) { id name ... } }

mutation { updateDeal(input: { id: String!, ... }) { id name ... } }

mutation { deleteDeal(id: "789") }

営業活動

# 作成のみ（更新・削除はGraphQL APIでは未提供）
mutation { createActivity(input: {
  accountId: String!  type: ActivityType!  occurredAt: String!  # ISO8601形式
  idempotencyKey: String!  # 重複登録防止キー（同一キーで再送した場合は既存を返す）
  dealId: String  contactId: String
  summary: String  detail: String
  externalSystem: String  externalId: String
  properties: [PropertyInput]
}) { id type occurredAt ... } }

---

型定義

ActivityType（営業活動タイプ）

値	説明
MEETING	打ち合わせ
NEGOTIATION	商談
CALL	電話
EMAIL	メール
OTHER	その他（タスク等）

契約ステータスID（案件）

値	説明
1	進行中
2	成約
3	失注

PropertyInput（カスタム項目）

input PropertyInput {
  name: String!   # カスタム項目の物理名
  value: String   # 値
}

---

注意事項