サポートの API、イベント、一括エクスポート
サポートモジュールで連携に必要なものをすべて解説します。チケット、スレッド、SLA、キュー、カタログ、エンタイトルメント、アンケートのエンドポイント、署名付きで再試行と再送に対応したイベント購読、カーソルで再開できるフィード、チケットとメッセージの一括エクスポート、そして他のヘルプデスクからの過去チケットの冪等なインポートです。すべてのエンドポイントには、対応するツールが MCP サーバーにもあります。
サポートは以前から汎用のレコード API で扱えました。チケットはレコードなので、一覧も作成もすでに動いていました。動かなかったのは、チケットの隣にあってレコードではないものすべてです。メッセージのスレッド、SLA タイマー、キュー、サービスカタログ、エンタイトルメントの残数、アンケートにはエンドポイントが 1 つもなく、連携はチケットを起票できても、それに返信できませんでした。
この記事では、サポートのエンドポイント、MCP サーバー上の同じツール群、再試行と再送に対応したイベント購読、再開可能なイベントフィード、そして他のヘルプデスクからチケットの履歴を取り込む方法を扱います。
はじめに - 設定 · API と開発者 で API キーを作成します。キーによってアカウントが特定され、すべての操作がそのアカウントに限定されます。 - 認証方法は API の他の部分と同じです。Authorization: Bearer に続けてキーを指定します。 - この記事で扱うものはすべて /api/v1/service の下にあり、ticket オブジェクトを対象とします。他のオブジェクトに限定されたキーからは到達できません。 - すべてのエンドポイントには対応するツールが MCP サーバーにもあるため、SellioCRM に接続した AI エージェントもまったく同じことができます。
チケット - GET /api/v1/service/tickets はチケットをフラットな行として一覧し、ステータス、優先度、キュー、担当者、フリーテキストで絞り込めます。前回の同期以降に変わったものだけを取得するには updated_since にタイムスタンプを指定し、ページングには limit と offset を使います。 - GET /api/v1/service/tickets/{id} は 1 件のチケットを SLA タイマー付きで返します。期限、一時停止中かどうか、初回返信の目標、次回返信の目標です。このタイマーこそがこのエンドポイントの存在理由です。汎用のレコードエンドポイントが返すのは項目であって、期限ではありません。 - POST /api/v1/service/tickets は、コンソールと同じ経路でチケットを起票します。受付番号、SLA の目標、ルーティングルール、送信 Webhook がすべて動きます。 - PATCH /api/v1/service/tickets/{id} はステータス、優先度、カテゴリ、キュー、担当者を変更します。担当者の割り当てはステータス変更と同じ動詞なので、専用のエンドポイントはありません。 - GET と POST の /api/v1/service/tickets/{id}/messages でスレッドを読み書きします。kind が public なら顧客に返信してメールを送信し、kind が internal なら担当者だけが見るメモを残します。 - POST /api/v1/service/tickets/merge は 2 件のチケットをマージします。従側が主側に吸収され、そのメッセージが移動します。
チケットの周辺 - GET /api/v1/service/queues は、担当者ごとの上限、営業時間、既定の優先度とともにキューを一覧します。振り分けの前にこれを読んでください。作成時に渡すのはキューの名称です。 - GET と POST の /api/v1/service/catalog で、サービスカタログの一覧を読み、品目を申し込みます。申し込みは、その品目のキューと優先度を持つ本物のチケットを作ります。独自の idempotencyKey を送れば、再試行時に 2 件目のチケットを作らず既存の申し込みが返ります。 - GET /api/v1/service/entitlements は、取引先または契約ごとのサポートのエンタイトルメントを、残数とともに返します。 - GET /api/v1/service/surveys は、満足度アンケートの招待を状態と回答日とともに返します。匿名アンケートで回答者が返ることはありません。
イベント · リアルタイムとカーソル 連携にはリアルタイムの両面が必要です。何かが起きた瞬間に知らされることと、停止していた間に取りこぼしたものに追いつくことです。前者は購読が、後者はフィードが担います。
- POST /api/v1/service/subscriptions は、URL と関心のあるイベントを登録します。events には正確な型か、ticket.* のようなファミリーのワイルドカードを指定できます。未知のイベントは名前で拒否されます。決して発火しない購読はエラーより悪いからです。シークレットは 1 回だけ返るので、控えておいてください。
- 配信は POST で届き、ヘッダーが 3 つ付きます。イベント名の x-sellio-event、その試行の id である x-sellio-delivery、そして sha256 に続けて本文そのものからシークレットで計算したコードを載せた x-sellio-signature です。受け取った側で再計算して比較し、一致しない場合はその呼び出しを破棄してください。
- 失敗した配信は、待ち時間を伸ばしながら再試行されます。おおよそ 1 分、5 分、30 分、2 時間、6 時間です。そのあとは配信不能として記録され、ログに残ります。
- GET /api/v1/service/deliveries は「このイベントは届いたのか」に対する参照可能な答えです。各行には試行回数、最後のステータスコード、エラー、次回の再試行予定が載ります。
- POST /api/v1/service/deliveries/{id}/replay は 1 件の配信を再送します。保存された本文を、最初に送ったものとバイト単位で同じ内容のまま再送します。ここでペイロードを組み立て直せば、昨日のタイムスタンプで今日の状態を送ることになってしまいます。
- GET /api/v1/service/events がフィードです。前回の応答で得たカーソルを渡すと、その時点より後に起きたものだけが返ります。nextCursor は空のページでも返るので、それを保存してください。カーソルは不透明な値として扱ってください。計算に使うと、あとで連携が黙って壊れます。
- GET /api/v1/service/event-types は、製品が送れるすべてのイベントと、3 つの Webhook レジストリのどれが購読できるか、そしてサービスの購読に届けるにはアカウントでイベントバスを有効にする必要があるかどうかを一覧します。購読を作る前に読んでください。
チケットとメッセージのエクスポート GET /api/v1/service/export は、entity に tickets または messages、format に json または csv を取ります。このエンドポイントが存在する理由はメッセージのエクスポートです。スレッドはレコードではないため、他のどの画面も一括では取り出せませんでした。絞り込みには since、status、queue、ticketId、kind を使い、ページングには limit（最大 500）と offset を使います。json の応答には hasMore が含まれるので、まだページが残っているかが分かります。
他のヘルプデスクから履歴を取り込む POST /api/v1/service/import は 1 回の呼び出しで最大 500 行を受け付けます。各行には、移行元ツールでのチケット番号である externalKey と、件名が必要です。加えて body、依頼者のメール・氏名・電話番号、priority、category、queue、channel、status、createdAt を含められます。
- インポートは externalKey によって冪等です。同じファイルを 2 回取り込んでも、重複せずに既存として報告されるので、失敗したバッチを安心して再実行できます。
- チケットは移行元の日付とステータスで作成されます。そうしなければ、クローズ済みの 1 万 5 千件が今日の日付で新規として入り、今まさに働いている人のキューをあふれさせ、期間別のあらゆるレポートでうそをつくことになります。
- dryRun を true にすると、何も書き込まずに何が起きるかを確認できます。
- 検証に失敗した行は、バッチ内の位置とともに problems の項目になり、残りの行は取り込まれます。3 行の日付が不正なだけで、最初からやり直す必要はありません。