Freshserviceとの連携を構築する場合、そのAPI機能を理解する必要があります。チケットの作成を自動化したり、ユーザーデータを同期したり、カスタムダッシュボードを構築したりする場合でも、Freshservice APIを使用すると、ITサービス管理データにプログラムでアクセスできます。
Freshservice APIが提供するもの、認証方法、利用可能なエンドポイント、およびレート制限内で作業する方法について説明しましょう。また、eesel AIのようなツールが、最初からコードを作成せずに、これらの統合の一部をどのように簡素化できるかについても見ていきます。
Freshservice APIとは？
Freshservice APIは、Freshserviceインスタンスとプログラムで対話できるRESTful（RESTful）インターフェースです。標準的なHTTP規約に従い、データ交換にはJSONを使用し、CRUD操作（作成、読み取り、更新、削除）の全範囲をサポートします。
これが実際に何を意味するのかを以下に示します。
- チケットデータを外部レポートツールにプルできます
- 監視アラートからチケットを自動的に作成できます
- ユーザー情報をIDプロバイダーと同期できます
- 発見ツールからアセットレコードを更新できます
- カスタムポータルまたはモバイルアプリを構築できます
Freshserviceは実際には2つのAPIバージョンを提供しています。バージョン1はレガシーAPIであり、まだ機能していますが、制限されています。バージョン2は、新しいプロジェクトで使用する必要があります。より高いレート制限、より優れたエラー処理、およびより多くのエンドポイントを提供します。v2 APIはJSONのみを受け入れ、HTTPS接続が必要です。
Freshserviceには3つの種類もあり、それぞれAPIの動作がわずかに異なります。
- Freshservice：標準のITSMプラットフォーム
- Freshservice for Business Teams (FSBT)：人事や施設などの非IT部門向けに設計されています
- Freshservice for MSPs：複数のクライアントを処理するマネージドサービスプロバイダー向けに構築されています
コアAPIは3つすべてで同じように機能しますが、一部のエンドポイントと用語が異なります。たとえば、MSPは「リクエスター（Requesters）」の代わりに「連絡先（Contacts）」を使用し、「ワークスペース（Workspaces）」の代わりに「クライアント（Clients）」を使用します。
認証方法
API呼び出しを行う前に、認証する必要があります。Freshserviceは、ユースケースに応じていくつかのオプションを提供します。
APIキー認証（推奨）
これは最も簡単で一般的なアプローチです。FreshserviceプロファイルからAPIキーを生成し、Basic Authを使用してリクエストに含めます。
APIキーを見つける方法は次のとおりです。
- Freshserviceポータルにログインします
- 右上のプロフィール写真をクリックします
- **プロフィール設定（Profile Settings）**に移動します
- APIキーは、パスワードの変更（Change Password）セクションの下に表示されます
キーを取得したら、Basic Authヘッダーでユーザー名としてキーを渡し、パスワードとして任意の文字列（慣例的に「X」）を渡して認証します。実際にどのように見えるかを以下に示します。
curl -u "your_api_key:X" \
-H "Content-Type: application/json" \
-X GET \
"https://yourdomain.freshservice.com/api/v2/tickets"
またはJavaScriptの場合：
const apiKey = "your_api_key_here";
const encodedKey = Buffer.from(apiKey + ":X").toString("base64");
fetch("https://yourdomain.freshservice.com/api/v2/tickets", {
method: "GET",
headers: {
"Authorization": `Basic ${encodedKey}`,
"Content-Type": "application/json"
}
})
.then(response => response.json())
.then(data => console.log(data));
ユーザー名とパスワード認証
Freshserviceのログイン資格情報を使用して認証することもできます。これはAPIキー認証と同じように機能しますが、代わりにメールアドレスとパスワードを渡します。
curl -u "user@company.com:password" \
-H "Content-Type: application/json" \
-X GET \
"https://yourdomain.freshservice.com/api/v2/tickets"
OAuth 2.0
（マーケットプレイスアプリのように）ユーザーの代わりにアクションを実行する必要があるアプリケーションの場合、FreshserviceはOAuth 2.0をサポートしています。これは設定がより複雑ですが、ユーザー向けの統合のセキュリティが向上します。
セキュリティのベストプラクティス
留意すべき点がいくつかあります。
- APIキーを安全に保管し、バージョン管理にコミットしないでください
- すべてのリクエストにHTTPSを使用します（v2では必須）
- APIキーを定期的にローテーションします
- 統合に必要な最小限の権限を使用します
- キーの保存に環境変数の使用を検討してください
コアAPIエンドポイントと機能
Freshservice APIは、プラットフォームのほぼすべての機能をカバーしています。作業する主なエンドポイントを以下に示します。
チケット（Tickets）
チケットエンドポイントは最も一般的に使用されます。次のことができます。
- フィルタリングとページネーションを使用してすべてのチケットをリストします
- プログラムで新しいチケットを作成します
- チケットのプロパティ（ステータス、優先度、担当者）を更新します
- チケットを削除または復元します
- 返信とメモを追加します
基本的なチケット作成リクエストは次のようになります。
fetch("https://yourdomain.freshservice.com/api/v2/tickets", {
method: "POST",
headers: {
"Authorization": "Basic " + btoa("api_key:X"),
"Content-Type": "application/json"
},
body: JSON.stringify({
email: "requester@example.com",
subject: "New laptop request",
description: "I need a new laptop for the upcoming project",
priority: 2,
status: 2
})
});
チケットのプロパティは、ステータスと優先度に数値を使用します。
| ステータス（Status） | 値（Value） |
|---|---|
| オープン（Open） | 2 |
| 保留中（Pending） | 3 |
| 解決済（Resolved） | 4 |
| クローズ（Closed） | 5 |
| 優先度（Priority） | 値（Value） |
|---|---|
| 低（Low） | 1 |
| 中（Medium） | 2 |
| 高（High） | 3 |
| 緊急（Urgent） | 4 |
ユーザーとグループ（Users and groups）
サービスデスクチームとリクエスターを管理します。
- エージェント（Agents）：チケットを処理するITスタッフ
- リクエスター（Requesters）：チケットを送信する従業員
- グループ（Groups）：特定のチケットタイプを処理するチーム
- 部門（Departments）：組織構造
アセット（Assets）
IT資産をライフサイクル全体にわたって追跡および管理します。
- アセットレコードを作成および更新します
- アセットをチケットに関連付けます
- アセットの関係と依存関係を管理します
- アセットのメンテナンスと契約を追跡します
変更と問題（Changes and problems）
ITILに準拠した変更管理の場合：
- 変更リクエストを作成します
- 変更承認ワークフローを管理します
- 変更をチケットと問題にリンクします
- 実装ステータスを追跡します
サービスカタログ（Service catalog）
サービスリクエストを自動化します。
- 利用可能なサービスアイテムをリストします
- サービスリクエストを送信します
- リクエストの承認ステータスを追跡します
- サービスレベルアグリーメントを管理します
会話（Conversations）
チケットのコミュニケーションを処理します。
- リクエスターに表示される公開返信を追加します
- 内部チームにプライベートノートを追加します
- 会話にファイルを添付します
- チケットを外部関係者に転送します
レート制限とベストプラクティス
Freshserviceは、プラットフォームの安定性を確保するためにレート制限を課しています。これらは、プランとアカウントが作成された時期によって異なります。
プランごとのレート制限
2020年9月1日以降に作成されたアカウントの場合：
| プラン（Plan） | 全体的な制限（1分あたり）（Overall Limit (per minute)） | チケット/リスト操作（1分あたり）（Ticket/List Operations (per minute)） |
|---|---|---|
| スターター（Starter） | 100 | 40 |
| グロース（Growth） | 200 | 70 |
| プロ（Pro） | 400 | 120 |
| エンタープライズ（Enterprise） | 500 | 140 |
これらは、ユーザーごとまたはIPごとではなく、アカウント全体の制限であることに注意してください。アカウントからのすべてのAPI呼び出しは、同じクォータにカウントされます。
レート制限ヘッダー
すべてのAPIレスポンスには、現在のレート制限ステータスを示すヘッダーが含まれています。
X-RateLimit-Total：アカウントの1分あたりの合計制限X-RateLimit-Remaining：現在のウィンドウに残っているリクエストX-RateLimit-Used-CurrentRequest：最後の呼び出しで使用したリクエスト数Retry-After：制限に達したときに待機する秒数（429レスポンスでのみ表示されます）
レート制限の処理
制限に達すると、APIは429ステータスコードを返します。コードはこれを適切に処理する必要があります。
async function makeRequestWithRetry(url, options, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
const response = await fetch(url, options);
if (response.status !== 429) {
return response.json();
}
const retryAfter = response.headers.get('Retry-After') || Math.pow(2, retries);
console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
retries++;
}
throw new Error('Maximum retries reached');
}
ページネーション（Pagination）
リストエンドポイントは、ページネーションされた結果を返します。pageパラメータを使用してナビゲートします。
curl -u "api_key:X" \
"https://yourdomain.freshservice.com/api/v2/tickets?page=2&per_page=100"
v2 APIは、最大100レコードのページサイズをサポートしています。1回の呼び出しですべての結果を取得できると想定するのではなく、常に本番環境の統合のためにページネーションを実装してください。
一般的な統合ユースケース
組織がFreshservice APIを使用する実際的な方法を以下に示します。
自動チケット作成：DatadogやPagerDutyなどの監視ツールは、アラートが発生したときにチケットを自動的に作成できるため、ITチームはインシデントに迅速に対応できます。
ユーザープロビジョニング：新しい従業員が入社すると、人事システムはFreshserviceアカウントを自動的に作成し、役割に基づいて適切な部門とグループに割り当てることができます。
アセット同期：ディスカバリーツールは、アセットデータをFreshserviceのCMDBにプッシュできるため、手動で入力しなくてもインベントリレコードを最新の状態に保つことができます。
カスタムダッシュボード：組織は、チケットメトリックをTableauやPower BIなどのビジネスインテリジェンスツールにプルして、エグゼクティブレポートを作成します。
チャットボット統合：AI搭載のサポートツールは、チャットの会話からチケットを作成し、コンテンツ分析に基づいて自動的に分類およびルーティングできます。
メール自動化：特定のドメインからの受信メール、または特定のキーワードを含む受信メールは、事前に入力されたカテゴリと担当者でチケットの作成をトリガーできます。
最初のAPI呼び出しを開始する
自分で試してみる準備はできましたか？クイックスタートガイドを次に示します。
まず、Freshserviceプロファイル設定からAPIキーを取得します。次に、ターミナルを開き、次のcURLコマンドを実行します（yourdomainとyour_api_keyを置き換えます）。
curl -u "your_api_key:X" \
-H "Content-Type: application/json" \
-X GET \
"https://yourdomain.freshservice.com/api/v2/tickets?page=1&per_page=1"
すべてが正常に機能すると、最新のチケットを含むJSONレスポンスが返されます。
探索には、Postmanが非常に役立ちます。新しいリクエストを作成し、認証をBasic Authに設定し、APIキーをユーザー名として、「X」をパスワードとして設定して、エンドポイントのテストを開始します。
Freshworksは、APIインタラクションを簡素化する公式のJavaScript/TypeScript SDKも提供しています。
const { Freshservice } = require("@freshworks/api-sdk");
const fs = new Freshservice("yourdomain", "your_api_key");
// Get all tickets
const tickets = await fs.tickets.list();
eesel AIによるFreshservice統合の簡素化
API統合を最初から構築するには、時間とエンジニアリングリソースが必要です。コードを記述せずにFreshserviceワークフローを自動化する必要がある場合は、eesel AIが代替アプローチを提供します。
当社のプラットフォームはFreshserviceに直接接続し、一般的なタスクにAI搭載の自動化を提供します。
- AIエージェント（AI Agent）：最前線のサポートチケットを自律的に処理し、人間の介入なしに一般的な問題を解決します
- AIコパイロット（AI Copilot）：エージェントがレビューして送信するための返信を下書きし、応答時間を短縮します
- AIトリアージ（AI Triage）：コンテンツに基づいて、受信チケットを自動的にタグ付け、ルーティング、および優先順位付けします
チケットを作成したりフィールドを更新したりするためにAPI呼び出しを記述する代わりに、平易な英語で自動化ルールを構成します。たとえば、「チケットに「パスワードリセット（password reset）」と記載されており、VIPユーザーからのものである場合は、シニアサポートグループに割り当て、優先度を高くマークします。」
セットアップには数週間ではなく数分かかります。Freshserviceアカウントを接続すると、当社のAIは既存のチケット、ヘルプセンターの記事、およびマクロから学習します。APIエンドポイントをマッピングしたり、レート制限を自分で処理したりする必要はありません。
カスタムAPI統合とAI自動化の両方が必要なチームにとって、これらのアプローチは互いに補完し合います。データ同期とシステム間の通信にはAPIを使用し、インテリジェントなチケット処理と応答の下書きにはeesel AIを使用します。
