Communitygithub.com

CraftOS-dev/CraftBot

Zoho CRM API連携スキル(管理されたOAuth認証)。リード、取引先担当者、顧客、商談などのCRMレコードの管理、検索、作成、更新、削除を行います。

CraftBot とは?

このスキルは、Maton Gatewayを介してZoho CRM APIへのアクセスを提供し、管理されたOAuth認証を自動的に処理します。リード、取引先担当者、顧客、商談、キャンペーン、タスク、通話、イベント、商品などの主要モジュールに対して、完全なCRUD操作(作成、読み取り、更新、削除)を実行できます。また、組織情報の取得、ユーザー管理、モジュールメタデータの取得、複雑な条件によるレコード検索、バルク操作もサポートしています。このスキルはClaude Code、Cursor、CodexなどのAIエージェントプラットフォームで使用するために設計されており、`MATON_API_KEY`環境変数とMaton Gatewayを通じたネットワークアクセスが必要です。接続管理は`ctrl.maton.ai`で行い、レスポンス形式は標準的なZoho CRM APIに準拠しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CraftOS-dev/CraftBot/tree/HEAD/skills/zoho-crm

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Zoho CRM

管理されたOAuth認証でZoho CRM APIにアクセスします。リード、取引先担当者、顧客、商談、その他のCRMモジュールに対して、検索やバルク操作を含む完全なCRUD操作を実行できます。組織詳細、ユーザー管理、モジュールメタデータの取得もサポートしています。

クイックスタート

# リード一覧表示
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

ベースURL

https://gateway.maton.ai/zoho-crm/crm/v8/{endpoint}

ゲートウェイはリクエストを www.zohoapis.com/crm/v8 にプロキシし、OAuthトークンを自動的に注入します。

認証

すべてのリクエストには、Authorization ヘッダーに Maton API キーが必要です。

Authorization: Bearer $MATON_API_KEY

環境変数: APIキーを MATON_API_KEY として設定します。

export MATON_API_KEY="YOUR_API_KEY"

APIキーの取得

  1. maton.ai でサインインまたはアカウントを作成します。
  2. maton.ai/settings にアクセスします。
  3. APIキーをコピーします。

接続管理

Zoho CRM OAuth接続は https://ctrl.maton.ai で管理します。

接続一覧

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-crm&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

接続作成

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-crm'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

接続取得

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "connection": {
    "connection_id": "e55c5bac-241a-4cc8-9db5-50d2cad09136",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-crm",
    "metadata": {}
  }
}

返された url をブラウザで開いてOAuth認証を完了します。

接続削除

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

接続の指定

複数のZoho CRM接続がある場合、Maton-Connection ヘッダーで使用する接続を指定します。

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'e55c5bac-241a-4cc8-9db5-50d2cad09136')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

省略された場合、ゲートウェイはデフォルト(最も古い)のアクティブな接続を使用します。

APIリファレンス

モジュール

Zoho CRMはデータをモジュールに整理します。主要なモジュールは次のとおりです。

モジュールAPI名説明
リードLeads見込み顧客
取引先担当者Contacts個人
顧客Accounts組織/企業
商談Deals販売機会
キャンペーンCampaignsマーケティングキャンペーン
タスクTasksやることリスト
通話Calls通話ログ
イベントEventsカレンダー予定
商品Products販売するアイテム

レコード一覧

GET /zoho-crm/crm/v8/{module_api_name}?fields={field1},{field2}

クエリパラメータ:

パラメータ型説明
fieldsstring必須. カンマ区切りのフィールドAPI名(最大50)
pageintegerページ番号(デフォルト: 1)
per_pageinteger1ページあたりのレコード数(デフォルト/最大: 200)
sort_bystring並び替え: id, Created_Time, Modified_Time
sort_orderstringasc または desc(デフォルト)
cvidlongカスタムビューID
page_tokenstring2000レコードを超えるページネーション用

例 - リード一覧:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email,Phone,Company')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "Last_Name": "Maclead (Sample)",
      "Phone": "555-555-5555",
      "Company": "Rangoni Of Florence",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "sort_by": "id",
    "sort_order": "desc",
    "more_records": false,
    "next_page_token": null
  }
}

例 - 取引先担当者一覧:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts?fields=First_Name,Last_Name,Email,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

例 - 顧客一覧:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts?fields=Account_Name,Website,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

例 - 商談一覧:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Deals?fields=Deal_Name,Stage,Amount')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レコード取得

GET /zoho-crm/crm/v8/{module_api_name}/{record_id}

例:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/7243485000000597000')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レコード作成

POST /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "field_api_name": "value"
    }
  ]
}

モジュール別必須フィールド:

モジュール必須フィールド
リードLast_Name
取引先担当者Last_Name
顧客Account_Name
商談Deal_Name, Stage
タスクSubject
通話Subject, Call_Type, Call_Start_Time, Call_Duration
イベントEvent_Title, Start_DateTime, End_DateTime

例 - リード作成:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Smith",
        "First_Name": "John",
        "Email": "[email protected]",
        "Company": "Acme Corp",
        "Phone": "+1-555-0123"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:10:56-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record added",
      "status": "success"
    }
  ]
}

例 - 取引先担当者作成:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Doe",
        "First_Name": "Jane",
        "Email": "[email protected]",
        "Phone": "+1-555-9876"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

例 - 顧客作成:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Account_Name": "Acme Corporation",
        "Website": "https://acme.com",
        "Phone": "+1-555-1234"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レコード更新

PUT /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "id": "record_id",
      "field_api_name": "updated_value"
    }
  ]
}

例:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "id": "7243485000000619001",
        "Phone": "+1-555-9999",
        "Company": "Updated Company Name"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:11:01-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record updated",
      "status": "success"
    }
  ]
}

レコード削除

DELETE /zoho-crm/crm/v8/{module_api_name}?ids={record_id1},{record_id2}

クエリパラメータ:

パラメータ型説明
idsstringカンマ区切りのレコードID(必須、最大100)
wf_triggerbooleanワークフローを実行するかどうか(デフォルト: true)

例:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?ids=7243485000000619001', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "7243485000000619001"
      },
      "message": "record deleted",
      "status": "success"
    }
  ]
}

レコード検索

GET /zoho-crm/crm/v8/{module_api_name}/search

クエリパラメータ(いずれか必須):

パラメータ型説明
criteriastring検索条件(例: (Last_Name:equals:Smith))
emailstringメールアドレスで検索
phonestring電話番号で検索
wordstring全体テキスト検索
pageintegerページ番号
per_pageinteger1ページあたりのレコード数(最大200)

条件の書式: ((field_api_name:operator:value) and/or (...))

演算子:

  • テキストフィールド: equals, not_equal, starts_with, in
  • 日付/数値フィールド: equals, not_equal, greater_than, less_than, between, in
  • ブールフィールド: equals, not_equal

例 - メールで検索:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/[email protected]')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

例 - 条件で検索:

python <<'EOF'
import urllib.request, os, json
import urllib.parse
criteria = urllib.parse.quote('(Last_Name:starts_with:Smith)')
req = urllib.request.Request(f'https://gateway.maton.ai/zoho-crm/crm/v8/Leads/search?criteria={criteria}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

レスポンス:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "Last_Name": "Maclead (Sample)",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

関連スキル