コンテンツへスキップ
無料で始める
← All articles
Setup

開発者向けリファレンス: REST APIとMCP

Sellio APIの完全なリファレンス: APIキー認証、フィールド検出、RESTエンドポイント、エラー形式、レート制限、AIエージェント向けのMCPサーバー。

HTTP経由でSellioと連携するか、MCP経由でAIエージェントを接続します。どちらの方法でも、同じキー、同じテナントスコープ、同じレート制限が使われます。任意のオブジェクトのフィールドを検出し、数分でレコードの読み書きを開始できます。

💡 www.selliocrm.com/developers にも同じリファレンスを掲載した開発者向けポータルがあり、アウトバウンドWebhook、ダウンロード可能なOpenAPI仕様、Postmanコレクションも用意されています。

認証

すべてのリクエストにはAuthorization: Bearerヘッダーで渡すAPIキーが必要です。このキーによって所有テナントが特定されるため、すべてが自動的にそのテナントに限定されます。キーをブラウザに露出させず、サーバーサイドでのみ使用してください。キーの生成と失効は設定 → API & 開発者で行います。

curl -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/objects

キーのスコープ

設定 → API & 開発者でキーを生成する際にスコープを選択します。各連携には必要なアクセス権のみを与えてください。制限はRESTとMCPで同じように適用されます。両方の窓口が同じキーと同じ制御を使用するためです。

  • 読み取り専用: キーはデータを読み取りますが、作成・編集・削除はできません。RESTではPOST、PATCH、DELETEを、MCPではcreate_record、update_record、delete_recordツールをブロックします。書き込みや削除を試みると403で { "error": "errors.apiKeyReadOnly" } が返ります。
  • オブジェクト限定: キーがアクセスできるオブジェクトを選択します。リスト外のオブジェクトは403で { "error": "errors.apiKeyObjectDenied" } を返します。オブジェクト一覧(GET /api/v1/objects およびlist_objectsツール)はすでにスコープでフィルタされた状態で返され、活動(/api/v1/activities)はactivityオブジェクトとして扱われます。キーはactivityがスコープに含まれている場合のみアクセスできます。
  • 削除の許可: デフォルトでは、書き込みが有効でもキーは削除を一切行いません。キー生成時に削除を有効にすると、DELETE /api/v1/{object}/{id} とMCPのdelete_recordツールが使えるようになります。このスコープがない場合、削除は403で { "error": "errors.apiKeyDeleteDenied" } を返します。削除はソフト削除で、レコードはゴミ箱に移動し復元できます。

スコープを設定しないキー(デフォルト)は、これまでどおりすべてのオブジェクトへの完全な読み書きアクセス権を持ちます。この変更以前に作成されたキーは、新しいスコープ付きキーを生成するまで完全なアクセス権を維持します。

OAuthと連携アプリ

サードパーティのシステムがユーザーに代わって連携する必要がある場合(顧客が管理者キーを貼り付ける必要がない場合)は、PKCE付きのOAuth 2.0認可コードフローを使用します。ユーザーには要求されたスコープの同意画面が表示され、承認すると、アプリは同意された範囲でのみ動作するアクセストークンを受け取ります。アプリは審査制です。開発者がアプリを登録・公開して client_id と client_secret を取得します。

  • client_id、redirect_uri(アプリの許可リストと完全一致)、scope、state、PKCE(code_challenge、code_challenge_method=S256)を付けて、ユーザーを GET /api/oauth/authorize にリダイレクトします。PKCEは必須です。
  • ログイン中のユーザーが同意画面で承認すると、CRMはcodeと同じstateを付けてリダイレクトし返します。
  • サーバー側で、code_verifier、client_id、client_secret、redirect_uriを付けて POST /api/oauth/token(grant_type=authorization_code)でコードをアクセストークン(Bearer、約1時間)とリフレッシュトークンに交換します。
  • v1 APIとMCPサーバーを Authorization: Bearer at_... で呼び出します。同意範囲に限定されます。grant_type=refresh_tokenで更新します。リフレッシュトークンはローテーションされ(古いものは使用時に無効化)、再利用があるとファミリー全体が失効します。POST /api/oauth/revoke で失効させられます。
# 1) Consent (the user approves → redirect_uri?code=...&state=...)
GET https://www.selliocrm.com/api/oauth/authorize?response_type=code&client_id=app_...&redirect_uri=https://your-app/callback&scope=records:read%20activities:read&state=abc&code_challenge=...&code_challenge_method=S256

# 2) Exchange the code for tokens (server-side)
curl -X POST https://www.selliocrm.com/api/oauth/token \
  -d grant_type=authorization_code -d code=<authcode> -d code_verifier=<verifier> \
  -d client_id=app_... -d client_secret=secret_... -d redirect_uri=https://your-app/callback

# → { "access_token": "at_...", "token_type": "Bearer", "expires_in": 3600,
#     "refresh_token": "rt_...", "scope": "records:read activities:read" }

OAuthスコープ: records:read と records:write(全オブジェクト)、records:read:contact と records:write:opportunity(オブジェクト単位)、activities:read と activities:write、objects:read(検出用)。これらはキーと同じ読み取り、書き込み、オブジェクト単位の制御にマッピングされます。

埋め込みウィジェット(iframe)

あなたのアプリは、レコード詳細画面やダッシュボードに独自の画面(ウィジェット)を埋め込めます。ウィジェットは、アプリの許可リストに登録された自社オリジンから配信されるサンドボックス化されたiframe内で動作し、widgets:embedスコープを要求します。テナント管理者は、各ウィジェットの表示位置をアプリ → インストール済みで選択します。

ホストはpostMessage(sellio:widget:context、version 1)経由でUIコンテキストのみをウィジェットに送信します: recordId、objectApiName、locale、theme、installId。ビジネスデータ、トークン、シークレットはこのメッセージには含まれません。データの読み書きには、ウィジェットは自身のOAuthトークン(インストール時に付与されたスコープ)を使ってOAuth APIを利用します。ウィジェットが返信できるのは sellio:widget:ready(コンテキストの再受信用)と、{ height } を伴う sellio:widget:resize(高さに合わせる。上限あり)のみで、それ以外のメッセージは無視されます。

セキュリティ: iframeはサンドボックス化されクロスオリジンであるため、ウィジェットはホストのDOMやCookieにアクセスできません。ホストはすべてのpostMessageで正確なオリジンを検証し、embedUrlは常にアプリの許可リストと照合されます。あなたのウィジェットでは、event.originがホストのオリジンである場合のみメッセージを受け付けてください。

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.selliocrm.com') return; // host only
  const msg = event.data;
  if (!msg || msg.version !== 1) return;
  if (msg.type === 'sellio:widget:context') {
    const { recordId, objectApiName, locale, theme } = msg.payload;
    // data: use the OAuth API with YOUR token (never comes over postMessage)
  }
});
parent.postMessage({ type: 'sellio:widget:ready', version: 1 }, 'https://www.selliocrm.com');

フィールド検出

レコードを作成・更新する前に、そのオブジェクトのフィールドを検出しましょう。何が存在するか、何が必須か、選択項目にどんな値を受け付けるかがわかります。推測する必要も、既存レコードを調べる必要もありません。

RESTでは、オブジェクトとそのフィールドを取得できます。required、options(選択項目用)、targetObject(参照用)を含みます。

GET https://www.selliocrm.com/api/v1/objects/contact

# → {
#   "apiName": "contact",
#   "label": "Contact",
#   "fields": [
#     { "apiName": "name",  "label": "Name",   "type": "text",  "required": true },
#     { "apiName": "email", "label": "Email",  "type": "email", "required": false },
#     { "apiName": "source", "label": "Source", "type": "select", "required": true,
#       "options": [ { "value": "site", "label": "Website" },
#                    { "value": "referral", "label": "Referral" } ] },
#     { "apiName": "company", "label": "Company", "type": "lookup",
#       "required": false, "targetObject": "company" }
#   ]
# }

MCPでは、describe_objectツールがエージェントに同じフィールドを返します。

{ "method": "tools/call",
  "params": { "name": "describe_object", "arguments": { "object": "contact" } } }

REST API v1

任意のオブジェクトのレコードを、JSONの送受信で扱います。{object} はapiName(例: contact、lead、opportunity)、{id} はレコードのuuidです。

  • GET /api/v1/objects: テナントのオブジェクト一覧。
  • GET /api/v1/objects/{object}: オブジェクトのフィールド(検出)。
  • GET /api/v1/{object}: レコードの一覧と検索。
  • GET /api/v1/{object}/{id}: レコード1件を取得。
  • POST /api/v1/{object}: レコードを作成。
  • POST /api/v1/{object}/bulk: 一括作成(最大500件、項目ごとの部分成功)。
  • PATCH /api/v1/{object}/{id}: フィールドを更新(部分更新)。
  • PATCH /api/v1/{object}/bulk: 一括更新({ updates: [{ id, ...fields }] })。
  • DELETE /api/v1/{object}/{id}: 削除(ソフト削除、ゴミ箱へ移動。キーに削除スコープが必要)。

一覧取得(GET)のパラメータ: limit(1〜500、デフォルト50)、offset(ページングのオフセット、デフォルト0。ページングなしの合計数はtotalフィールドに含まれます)、search(名前で検索、大文字小文字・アクセント記号を区別しない)、order(並び替えるフィールドに :asc または :desc を付与)、filter。高度なフィルタ: filter=field:operator:value を繰り返すことで論理AND(ORはなし、1回の呼び出しで最大12個)で複数条件を組み合わせられます。演算子: eq、neq、contains、gt、lt、gte、lte、empty、not_empty(emptyとnot_emptyは値を取りません)。演算子なしの旧形式 filter=field:value は完全一致を意味します。

# List (limit, offset, search, filter, order)
curl -H "Authorization: Bearer sk_live_..." \
  "https://www.selliocrm.com/api/v1/opportunity?limit=20&order=updated_at:desc&filter=stage:won"

# Rich filters (logical AND: amount >= 1000 AND stage = won)
curl -H "Authorization: Bearer sk_live_..." \
  "https://www.selliocrm.com/api/v1/opportunity?filter=amount:gte:1000&filter=stage:eq:won"

# One record
curl -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/contact/8f3c...

# Create
curl -X POST -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Souza","email":"ana@acme.com","source":"site"}' \
  https://www.selliocrm.com/api/v1/contact

# Bulk create (partial success per item)
curl -X POST -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"records":[{"name":"Ana"},{"name":"Bruno"}]}' \
  https://www.selliocrm.com/api/v1/contact/bulk
# → { "results": [ { "index": 0, "ok": true, "id": "..." } ], "created": 1, "failed": 0 }

# Update (partial)
curl -X PATCH -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source":"referral"}' \
  https://www.selliocrm.com/api/v1/contact/8f3c...

# Delete (soft, goes to the trash; requires the delete scope on the key)
curl -X DELETE -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/contact/8f3c...

エラー形式

エラーは { "error": "message" } の形式のJSONで、対応するHTTPステータスとともに返されます。

{ "error": "required field: source" }   # HTTP 400
  • 200と201: 成功(作成時は201)。
  • 400: バリデーションまたはビジネスルール違反。
  • 401: キーが欠落または無効。
  • 403: (RBACによる)オブジェクトへの権限なし、またはキーのスコープによるブロック(読み取り専用、スコープ外のオブジェクト、削除が無効など)。
  • 404: オブジェクトまたはレコードが見つからない(存在しないidへのDELETE/PATCHも含む)。
  • 429: レート制限超過(Retry-Afterヘッダーを参照)。

MCPサーバー(AIエージェント)

Sellioは、AIエージェントが安全にCRMを読み書きできるようにネイティブのMCP(Model Context Protocol)サーバーを提供しています。同じAPIキー、同じレート制限、同じバリデーション、同じRBACが適用されます。サーバーのURLは https://www.selliocrm.com/api/mcp です。

  • list_objects: テナントのオブジェクト一覧。
  • describe_object: オブジェクトのフィールド(必須項目、型、選択肢)。
  • list_records: レコードの一覧と検索。
  • get_record: idでレコード1件を取得。
  • create_record: レコードを作成。
  • update_record: フィールドを更新。
  • delete_record: 削除(ソフト削除、ゴミ箱へ移動)。キーに削除スコープが必要です。

HTTP経由のリモートMCPに対応するクライアントは、Authorization: Bearerヘッダー付きでこのURLを使用します。ネイティブなリモートHTTPに対応していないクライアントでは、mcp-remoteブリッジを使用します。

{
  "mcpServers": {
    "sellio-crm": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.selliocrm.com/api/mcp",
        "--header", "Authorization: Bearer sk_live_..."
      ]
    }
  }
}

レート制限

各キーには1分あたりの上限(デフォルト120、設定変更可能)があります。レスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset の各ヘッダーが含まれます。超過するとAPIは429とRetry-Afterを返します。

オブジェクトモデル

各テナントには標準オブジェクト(Contact、Company、Lead、Opportunityなど)とノーコードのカスタムオブジェクトがあります。GET /api/v1/objects ですべて検出でき、それぞれのフィールドは GET /api/v1/objects/{object} またはdescribe_objectで確認できます。スキーマは常にあなたのテナント固有のものです。

💡 設定 → API & 開発者でキーを生成し、数分で最初の呼び出しを行いましょう。レコードの削除はREST APIとMCPの両方で利用できますが、ソフト削除(ゴミ箱へ移動、復元可能)であり、削除スコープが有効なキー(デフォルトは無効)でのみ機能します。

Open this article inside the system →

Read it and want to see it working?

The account is free and the whole manual is available inside the system, with an assistant that answers from this very content.

無料アカウントを作成
開発者向けリファレンス: REST APIとMCP · Sellio