APIを使用してZendeskチケットを作成する方法：完全なJSONガイド

Zendeskとの連携を構築している場合、プログラムでチケットを作成する必要がある可能性が高くなります。カスタムWebフォームの接続、別のシステムからのデータの同期、サポートワークフローの自動化など、Zendesk Tickets API（ZendeskチケットAPI）は、Zendeskにデータを入力するための標準的な方法です。

このガイドでは、認証から高度なJSONペイロードまで、API経由でチケットを作成するために知っておく必要のあるすべての手順を説明します。

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

API呼び出しを開始する前に、次の基本事項がカバーされていることを確認してください。

• 管理者またはエージェントアクセス権を持つZendesk Supportアカウント。お持ちでない場合は、開発用の無料トライアルアカウントを入手できます。
• 管理センターの「アプリと連携」>「API」>「APIトークン」でAPIトークンアクセスが有効になっていること
• HTTPリクエストとJSONデータ構造に関する基本的な知識
• API呼び出しを行うためのツール：cURL、requestsライブラリを使用したPython、またはJavaScript環境

REST APIの操作に慣れていない場合は、Zendeskドキュメントに、セットアップなしでブラウザのJavaScriptコンソールを使用してリクエストをテストできる役立つクイックスタートガイドがあります。

Zendesk Tickets API（ZendeskチケットAPI）エンドポイントについて

Zendesk APIのチケット作成JSONエンドポイントは、すべてのZendeskインスタンスで一貫したパターンに従います。

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

エンドポイントについて知っておく必要のあることは次のとおりです。

• HTTPメソッド：新しいチケットを作成するためのPOST
• Content-Typeヘッダー：application/jsonに設定する必要があります
• 認証：メールとAPIトークンを使用したベーシック認証
• レート制限：ほとんどのエンドポイントで1分あたり700リクエスト

APIは、成功時に201 Createdステータスを返し、新しく割り当てられたチケットIDを含む完全なチケットオブジェクトを返します。問題が発生した場合は、問題を説明するエラーメッセージとともに4xxまたは5xxステータスが表示されます。

API認証の設定

認証は、ほとんどの開発者が最初に引っかかる場所です。Zendeskは、パスワードの代わりにAPIトークンを使用するというひねりを加えたベーシック認証を使用します。

APIトークンの生成

1. 管理者としてZendeskにサインインします
2. 管理センター>「アプリと連携」>「API」>「APIトークン」に移動します
3. プラスアイコンをクリックしてトークンを追加します
4. 説明的な名前（「チケット作成スクリプト」など）を付けます
5. トークンをすぐにコピーします（再度表示されることはありません）

認証形式

資格情報は次の形式に従います。

ユーザー名：{あなたのメールアドレス}/token
パスワード：{あなたのAPIトークン}

たとえば、メールアドレスがadmin@company.comで、トークンがabc123xyzの場合、次を使用します。

ユーザー名：admin@company.com/token
パスワード：abc123xyz

セキュリティのベストプラクティス

スクリプトにAPI資格情報をハードコードしないでください。代わりに、環境変数を使用します。

import os

ZENDESK_SUBDOMAIN = os.getenv('ZENDESK_SUBDOMAIN')
ZENDESK_API_TOKEN = os.getenv('ZENDESK_API_TOKEN')
ZENDESK_USER_EMAIL = os.getenv('ZENDESK_USER_EMAIL')

これにより、資格情報がバージョン管理から除外され、コードが環境間で移植しやすくなります。

基本的なチケット作成JSON構造

最小限、Zendeskチケットには件名とコメントの2つが必要です。これが最も単純な有効なJSONペイロードです。

{
  "ticket": {
    "subject": "プリンターが燃えています！",
    "comment": {
      "body": "煙がとてもカラフルです。"
    }
  }
}

ticketオブジェクトはすべてをラップします。内部では、次を設定します。

• subject：チケットのタイトル（必須）
• comment：少なくともbodyを含むオブジェクト（必須）

デフォルトでは、コメントは公開されています。代わりに内部メモを作成する場合は、"public": falseをコメントオブジェクトに追加します。

レスポンス形式

リクエストが成功すると、APIは作成されたチケットを返します。

{
  "ticket": {
    "id": 35436,
    "url": "https://company.zendesk.com/api/v2/tickets/35436.json",
    "subject": "プリンターが燃えています！",
    "status": "open",
    "created_at": "2026-03-01T22:55:29Z",
    ...
  }
}

idフィールドは、今後のAPI呼び出しでこのチケットを参照するために使用するものです。

チケットを作成するためのコード例

3つの一般的な言語での作業例を見てみましょう。

cURLの例

curl https://yourcompany.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "テストチケット", "comment": {"body": "これはテストです"}}}' \
  -H "Content-Type: application/json" \
  -v -u your@email.com/token:your_api_token \
  -X POST

-vフラグは詳細な出力を表示し、デバッグに役立ちます。本番環境では削除してください。

Pythonの例

import requests
import os
import json

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_USER_EMAIL')
token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', token)
headers = {'Content-Type': 'application/json'}

data = {
    'ticket': {
        'subject': 'プリンターの問題',
        'comment': {
            'body': 'プリンターが応答していません。',
            'public': True
        }
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

if response.status_code == 201:
    ticket = response.json()['ticket']
    print(f"作成されたチケット #{ticket['id']}")
else:
    print(f"エラー: {response.status_code}")
    print(response.text)

json=パラメーターを指定したrequests.post()は、ディクショナリをJSONに自動的にシリアル化し、Content-Typeヘッダーを設定することに注意してください。

JavaScriptの例

Zendeskがすでにロードされたブラウザで作業している場合は、jQueryを使用できます。

const ticket = {
  ticket: {
    subject: 'ログインのヘルプ',
    comment: {
      body: 'アカウントにアクセスできません。'
    }
  }
};

$.ajax({
  url: '/api/v2/tickets.json',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify(ticket)
}).done(data => {
  console.log('作成されたチケット:', data.ticket.id);
}).fail(err => {
  console.error('エラー:', err);
});

Node.jsの場合は、ネイティブのfetch APIまたはaxiosのようなライブラリを使用します。

const response = await fetch('https://company.zendesk.com/api/v2/tickets.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64')
  },
  body: JSON.stringify(ticket)
});

const data = await response.json();

高度なチケットプロパティ

基本をマスターしたら、追加のプロパティを設定して、より完全なチケットを作成できます。

カスタムフィールド

Zendeskインスタンスにカスタムチケットフィールドがある場合は、フィールドIDを使用して設定します。

{
  "ticket": {
    "subject": "注文の問い合わせ",
    "comment": {"body": "最近の注文に関する質問"},
    "custom_fields": [
      {"id": 25356371, "value": "ORD-12345"},
      {"id": 25356634, "value": "2026-03-01"}
    ]
  }
}

ドロップダウンフィールドの場合は、タグ値（表示テキストではない）を使用します。複数選択フィールドの場合は、タグ値の配列を渡します。

リクエスタの設定

他の人に代わってチケットを作成できます。

{
  "ticket": {
    "subject": "サポートリクエスト",
    "comment": {"body": "請求に関するヘルプが必要です"},
    "requester": {
      "name": "John Smith",
      "email": "john@example.com",
      "locale_id": 8
    }
  }
}

メールアドレスがZendeskに存在しない場合、新しいユーザープロファイルが自動的に作成されます。

コラボレーターとフォロワー

コラボレーター（更新を受信するユーザー）またはフォロワー（チケットを追跡するエージェント）を追加します。

{
  "ticket": {
    "subject": "チームの問題",
    "comment": {"body": "これは複数の部門に影響します"},
    "collaborators": ["user1@example.com", "user2@example.com"],
    "followers": [
      {"user_email": "agent@company.com", "action": "put"}
    ]
  }
}

ファイル添付

ファイルを添付するには、最初にファイルを個別にアップロードしてアップロードトークンを取得し、そのトークンをチケットの作成に含める必要があります。

{
  "ticket": {
    "subject": "スクリーンショットが添付されています",
    "comment": {
      "body": "添付のエラーメッセージを参照してください",
      "uploads": ["vz7ll9ud8oofowy"]
    }
  }
}

非同期作成

処理に時間がかかる可能性のある複雑なビジネスルールを持つチケットの場合は、非同期作成を使用します。

POST /api/v2/tickets.json?async=true

これにより、完了を確認するためにポーリングできるジョブステータスとともに、202 Acceptedがすぐに返されます。

べき等性キー

失敗したリクエストを再試行するときに重複チケットを防ぐには、べき等性キーを含めます。

curl ... -H "Idempotency-Key: unique-request-id-123"

キーは2時間後に期限切れになります。異なるパラメーターで同じキーを再利用すると、エラーが返されます。

一般的なエラーとトラブルシューティング

発生する可能性が最も高いエラーとその修正方法を次に示します。

422 処理できないエンティティ

これは通常、JSONの形式が正しくないことを意味します。一般的な原因：

• プロパティ名または文字列値の周りの引用符がありません
• JSONオブジェクトに末尾のカンマがあります
• 二重引用符の代わりに単一引用符を使用しています
• 文字列に無効なエスケープシーケンスがあります

JSON文字列を手動で構築している場合（特にVBAまたは古い言語の場合）、余分な引用符文字に注意してください。JSONは次のようになります。

{"ticket": {"subject": "テスト", "comment": {"body": "こんにちは"}}}

次のようではありません。

"{"ticket": {"subject": "テスト"}}"

401 認証されていません

認証資格情報が正しくありません。確認してください：

• メールアドレスは正しいですか？
• メールアドレスの後に/tokenを含めましたか？
• APIトークンは有効で、期限切れになっていませんか？
• ユーザーにチケットを作成する権限がありますか？

429 レート制限を超えました

APIレート制限に達しました。Zendeskでは、ほとんどのエンドポイントで1分あたり700リクエストが許可されています。多くのチケットを作成する必要がある場合は、リクエスト間に遅延を追加するか、一括チケット作成エンドポイントを使用します。

フィールドエラーのある400不正なリクエスト

これは、チケットフィールドの値が無効な場合に発生します。

• カスタムフィールドIDが存在しません
• ドロップダウンの値が利用可能なオプションと一致しません
• 必須フィールドがありません
• 日付形式が正しくありません（ISO 8601を使用：2026-03-01）

コードなしでチケット作成を自動化する

API連携の構築と維持には時間がかかります。認証、エラー再試行ロジック、レート制限、およびAPIの変更に伴う継続的なメンテナンスを処理する必要があります。

目標がカスタム連携を構築するのではなく、チケット作成を自動化することである場合は、実際にコードを記述する必要があるかどうかを検討してください。eesel AIのようなツールは、開発作業なしでチケットの作成と応答を処理できます。

違いは次のとおりです。APIアプローチでは、人間が応答するチケットを作成するスクリプトを記述しています。AIエージェントを使用すると、ビジネスを理解し、作成から解決までのチケットライフサイクル全体を処理するようにシステムをトレーニングしています。Zendeskアカウントに接続すると、過去のチケット、ヘルプセンターの記事、マクロから学習します。

プログレッシブロールアウトモデルは、AIがレビュー用の応答を下書きすることから始まり、それが証明されるにつれて完全な自動化に拡張することを意味します。チケットの作成を自動化するだけでなく、チケット量を削減しようとしているチームにとって、これはカスタムAPI開発よりも多くの場合、より迅速な結果をもたらします。