Zendesk APIを使用して組織を作成する方法：完全ガイド

組織（Organization）は、Zendeskが大規模な顧客関係を管理するための最も強力な機能の1つです。組織を使用すると、ユーザーをグループ化したり、チケットを自動的にルーティングしたり、サポートのやり取りの可視性を制御したりできます。Zendeskインターフェースから手動で組織を作成できますが、その真の力は、Zendesk APIを介してこのプロセスを自動化することから生まれます。

別のプラットフォームから移行する場合でも、CRMと同期する場合でも、セルフサービスのサインアップフローを構築する場合でも、Zendesk Organizations APIを介して組織を作成する方法を知ることは、本格的な実装には不可欠です。このガイドでは、認証からエッジケースの処理まで、知っておく必要のあるすべてのことを説明します。基本的なAPI呼び出しを超えて組織管理を自動化する場合は、eesel AIがワークフロー全体を処理できます。

開始するために必要なもの

コードに入る前に、次の前提条件が整っていることを確認してください。

• 管理者アクセス権を持つZendeskアカウント。 APIを介して組織を作成できるのは、カスタムロールを持つ管理者とエージェントのみです。
• APIトークン。 これは、Zendesk管理センターの「アプリと連携」>「API」>「Zendesk API」で生成する必要があります。
• Zendeskサブドメイン。 これは、Zendesk URLの最初の部分です（例：yourcompany.zendesk.comのyourcompany）。
• HTTPリクエストを行うためのツール。 cURL、Python、JavaScriptを使用した例を示しますので、スタックに適したものを選択してください。

Zendesk APIは、メールアドレスとAPIトークンの組み合わせによる基本認証を使用します。これは、パスワードを使用するよりも安全であり、アクセスをきめ細かく制御できます。

ステップ1：Zendesk APIトークンを生成する

APIトークンは、コードがZendeskで認証するためのキーです。作成方法は次のとおりです。

1. 管理者としてZendeskアカウントにログインします
2. サイドバーの管理センターアイコンをクリックします
3. アプリと連携 > API > Zendesk APIに移動します
4. 設定タブをクリックします
5. トークンアクセスがまだオンになっていない場合は有効にします
6. **プラス（+）**アイコンをクリックして、新しいトークンを追加します
7. 「組織管理API」などのわかりやすい名前を付けます
8. トークンをすぐにコピーします（Zendeskは一度しか表示しません）

このトークンを安全に保管してください。パスワードのように扱ってください。トークンを持っている人は誰でも、APIを介してZendeskデータにアクセスできます。

プロのヒント： 1つのトークンをすべての場所で再利用するのではなく、さまざまな統合に対して個別のトークンを作成します。これにより、他のシステムを壊すことなく、必要に応じてアクセスを取り消すことが容易になります。

ステップ2：組織エンドポイントを理解する

Organizations APIは、REST規約に従います。組織を作成するには、次のURLにPOSTリクエストを行います。

https://{サブドメイン}.zendesk.com/api/v2/organizations

リクエストボディは、組織のプロパティを含むJSONオブジェクトです。最小限の作成リクエストは次のようになります。

{
  "organization": {
    "name": "Acme Corporation"
  }
}

必須フィールドはnameのみで、Zendeskアカウント全体で一意である必要があります。名前にパイプ文字（|）を含めることはできません。含めると、リクエストは失敗します。

基本を超えて、いくつかの便利なプロパティを設定できます。

認証にはHTTP基本認証を使用します。メールアドレスと/token:、APIトークンを組み合わせて、結果をBase64エンコードします。ヘッダーは次のようになります。

Authorization: Basic {base64_encoded_credentials}

ステップ3：最初の組織を作成する

これを実際のコード例で実践してみましょう。各例では、実際に使用する一般的なフィールドを持つ組織を作成します。

cURLの使用

SUBDOMAIN="yourcompany"
EMAIL="admin@yourcompany.com"
TOKEN="your_api_token_here"

curl -X POST "https://${SUBDOMAIN}.zendesk.com/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -d '{
    "organization": {
      "name": "Acme Corporation",
      "domain_names": ["acme.com", "acmecorp.com"],
      "external_id": "CRM-12345",
      "tags": ["enterprise", "priority"],
      "details": "Enterprise customer since 2020"
    }
  }'

Pythonの使用

import requests
import base64

subdomain = "yourcompany"
email = "admin@yourcompany.com"
token = "your_api_token_here"

credentials = base64.b64encode(
    f"{email}/token:{token}".encode()
).decode()

organization = {
    "organization": {
        "name": "Acme Corporation",
        "domain_names": ["acme.com", "acmecorp.com"],
        "external_id": "CRM-12345",
        "tags": ["enterprise", "priority"],
        "details": "Enterprise customer since 2020"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/organizations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {credentials}"
    },
    json=organization
)

if response.status_code == 201:
    created_org = response.json()["organization"]
    print(f"Created organization ID: {created_org['id']}")
    print(f"Name: {created_org['name']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

JavaScript/Node.jsの使用

const axios = require('axios');

// Configuration
const config = {
  subdomain: 'yourcompany',
  email: 'admin@yourcompany.com',
  token: 'your_api_token_here'
};

// Organization data
const organization = {
  organization: {
    name: 'Acme Corporation',
    domain_names: ['acme.com', 'acmecorp.com'],
    external_id: 'CRM-12345',
    tags: ['enterprise', 'priority'],
    details: 'Enterprise customer since 2020'
  }
};

// Make the request
axios.post(
  `https://${config.subdomain}.zendesk.com/api/v2/organizations`,
  organization,
  {
    headers: {
      'Content-Type': 'application/json'
    },
    auth: {
      username: `${config.email}/token`,
      password: config.token
    }
  }
)
.then(response => {
  const org = response.data.organization;
  console.log(`Created organization ID: ${org.id}`);
  console.log(`Name: ${org.name}`);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

作成が成功すると、HTTP 201が返され、自動生成されたidフィールドを含む完全な組織オブジェクトが返されます。このidフィールドは、今後の更新に必要になります。

ステップ4：カスタム組織フィールドを操作する

ほとんどのZendesk実装では、カスタムフィールドを使用して、アカウント層、地域、CRM IDなどの追加の組織データを保存します。APIを介してこれらを操作する方法を次に示します。

まず、どのようなカスタムフィールドが存在するかを知る必要があります。これらは、Zendesk管理センターのオブジェクトとルール > 組織 > フィールドで確認するか、APIを介して取得できます。

curl "https://{サブドメイン}.zendesk.com/api/v2/organization_fields" \
  -u "{email}/token:{token}"

各カスタムフィールドには、一意のキー（account_tierやregionなど）があります。組織を作成または更新するときは、これらをorganization_fieldsオブジェクトに含めます。

{
  "organization": {
    "name": "Acme Corporation",
    "organization_fields": {
      "account_tier": "enterprise",
      "region": "north_america",
      "crm_id": "CRM-12345",
      "contract_value": 50000
    }
  }
}

値の形式は、フィールドタイプによって異なります。

• テキストフィールド： 文字列値
• ドロップダウンフィールド： オプションタグの値（表示名ではない）
• 数値フィールド： 数値（文字列ではない）
• 日付フィールド： ISO 8601形式（2024-01-15）
• チェックボックスフィールド： ブール値（trueまたはfalse）

一般的なユースケース： CRMから組織データを同期します。プライマリシステムでアカウントの詳細が変更されるたびに、Zendeskに更新をプッシュするWebhookまたはスケジュールされたジョブを設定します。これにより、サポートエージェントは最新の情報を使用して作業できます。

ステップ5：エラーとエッジケースを処理する

本番環境のコードでは、問題が発生した場合の処理が必要です。発生する可能性のある最も一般的なエラーを次に示します。

401 Unauthorized（認証されていません）

これは、認証情報が無効であることを意味します。以下を確認してください。

• APIトークンが正しく、取り消されていないこと
• メールアドレスがトークンを所有するアカウントと一致すること
• 正しい形式を使用していること：email/token:token（/token:の部分に注意）

422 Unprocessable Entity（処理できないエンティティ）

リクエストは理解されましたが、処理できませんでした。一般的な原因：

• 重複した名前： 組織名は一意である必要があります。最初に既存の組織を確認してください。
• 無効な文字： 名前にパイプ文字（|）を含めることはできません。
• 必須フィールドの欠落： nameフィールドは必須です。
• 無効なカスタムフィールド値： ドロップダウン値が定義されたオプションと正確に一致していることを確認してください。

429 Too Many Requests（リクエストが多すぎます）

Zendeskのレート制限に達しました。Organizations APIでは、1分あたり700リクエストが許可されています。組織を一括で作成する必要がある場合は、リクエスト間に遅延を追加します。

import time

for org_data in organizations:
    response = requests.post(url, json=org_data, auth=auth)
    if response.status_code == 429:
        # Wait and retry
        time.sleep(1)
        response = requests.post(url, json=org_data, auth=auth)
    # Process response...
    time.sleep(0.1)  # Be nice to the API

ベストプラクティス： 統合を構築するときは、常にレスポンスステータスコードを確認し、429エラーに対して指数バックオフを実装してください。失敗したリクエストをログに記録して、後で再試行できるようにします。

eesel AIを使用した組織管理の自動化

組織を手動で管理することは、規模が大きくなるにつれて困難になります。顧客ベースが拡大するにつれて、Zendesk組織をCRM、請求システム、およびその他のツールと同期させ続けることは、大きな運用上の負担になります。

ここで、私たちがお手伝いできます。eesel AIでは、Zendeskと直接統合し、組織ベースのワークフローを自動化できるAIチームメイトを構築しました。

お客様がeesel AIを組織でどのように使用しているかを次に示します。

• 自動組織割り当て： チケットが届くと、AIはCRMでリクエスターを検索し、Zendeskで組織を作成または更新し、組織のプロパティに基づいてチケットを適切なチームにルーティングできます。
• スマートエスカレーション： 組織のカスタムフィールド（アカウント層やSLAレベルなど）を読み取り、エンタープライズ顧客からのチケットを自動的にエスカレーションできます。
• 組織を認識した応答： AIは、契約条件、専任のアカウントマネージャー、または以前の問題など、組織固有の詳細を参照する返信を作成します。

カスタムAPI統合の構築とは異なり、eesel AIは既存のデータとワークフローから学習します。必要なことを平易な英語で説明すると（「組織層がエンタープライズの場合は、アカウントマネージャーをCCする」など）、AIがAPI呼び出し、エラー処理、およびロジックを処理します。

AI Copilotがエージェントのレビュー用に返信を作成することから始めて、自信を深めるにつれて完全な自動化にレベルアップできます。ほとんどのチームは2か月以内に回収できます。

Zendesk Organizations APIを使用した構築を開始する

これで、Zendeskで組織をプログラムで作成および管理するために必要なものがすべて揃いました。主な手順をまとめましょう。

1. Zendesk管理センターからAPIトークンを生成します
2. 組織データを使用して、/api/v2/organizationsへのPOSTリクエストを構造化します
3. JSONレスポンスを処理して、作成された組織のIDを取得します
4. カスタムフィールドを使用して、組織固有のデータを保存します
5. 本番環境のコードに対して適切なエラー処理を実装します

Organizations APIはほんの始まりにすぎません。組織の更新、重複の統合、組織メンバーシップの管理、および組織ベースのビジネスルールの設定も可能です。

一括インポートや他のシステムとの双方向同期などの高度なユースケースでは、AI搭載ソリューションがチームの時間を節約できるかどうかを検討してください。eesel AIを7日間無料でお試しいただき、自動化がサポート業務をどのように変革できるかをご確認ください。