Back to Details

zendesk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshooting

故障排查

If requests fail, run 
zero doctor check-connector --env-name ZENDESK_API_TOKEN
or 
zero doctor check-connector --url https://your-subdomain.zendesk.com/api/v2/tickets.json --method GET
如果请求失败，请运行
zero doctor check-connector --env-name ZENDESK_API_TOKEN
或
zero doctor check-connector --url https://your-subdomain.zendesk.com/api/v2/tickets.json --method GET

How to Use

使用方法

All examples assume environment variables are set.
Base URL: 
https://{subdomain}.zendesk.com/api/v2/
Authentication: API Token via 
-u
flag
bash
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
Note: The 
-u
flag automatically handles Base64 encoding for you.
所有示例均假设已设置环境变量。
基础URL：
https://{subdomain}.zendesk.com/api/v2/
身份验证：通过
-u
标志使用API Token
bash
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
注意：
-u
标志会自动为您处理Base64编码。

Core APIs

核心API

1. List Tickets

1. 列出工单

Get all tickets (paginated):
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.tickets[] | {id, subject, status, priority}
With pagination:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json?page=1&per_page=50" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
获取所有工单（分页）：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.tickets[] | {id, subject, status, priority}
分页查询：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json?page=1&per_page=50" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"

2. Get Ticket

2. 获取工单详情

Retrieve a specific ticket:
bash
TICKET_ID="123"

curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
检索特定工单：
bash
TICKET_ID="123"

curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"

3. Create Ticket

3. 创建工单

Create a new support ticket:
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "subject": "My printer is on fire!",
    "comment": {
      "body": "The smoke is very colorful."
    },
    "priority": "urgent"
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
Create ticket with more details:
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "subject": "Need help with account",
    "comment": {
      "body": "I cannot access my account settings."
    },
    "priority": "high",
    "status": "open",
    "type": "problem",
    "tags": ["account", "access"]
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建新的支持工单：
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "subject": "My printer is on fire!",
    "comment": {
      "body": "The smoke is very colorful."
    },
    "priority": "urgent"
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建包含更多详情的工单：
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "subject": "Need help with account",
    "comment": {
      "body": "I cannot access my account settings."
    },
    "priority": "high",
    "status": "open",
    "type": "problem",
    "tags": ["account", "access"]
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

4. Update Ticket

4. 更新工单

Update an existing ticket:
bash
TICKET_ID="123"
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "status": "solved",
    "comment": {
      "body": "Issue has been resolved. Thank you!",
      "public": true
    }
  }
}
Then run:
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
Change priority and assignee:
bash
TICKET_ID="123"
ASSIGNEE_ID="456"
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "priority": "high",
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER
  }
}
Then run:
bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
更新现有工单：
bash
TICKET_ID="123"
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "status": "solved",
    "comment": {
      "body": "Issue has been resolved. Thank you!",
      "public": true
    }
  }
}
然后运行：
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
修改优先级与经办人：
bash
TICKET_ID="123"
ASSIGNEE_ID="456"
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "priority": "high",
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER
  }
}
然后运行：
bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

5. Delete Ticket

5. 删除工单

Permanently delete a ticket:
bash
TICKET_ID="123"

curl -s -X DELETE "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
永久删除工单：
bash
TICKET_ID="123"

curl -s -X DELETE "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"

6. Create Multiple Tickets

6. 批量创建工单

Bulk create tickets:
Write to 
/tmp/zendesk_request.json
:
json
{
  "tickets": [
    {
      "subject": "Ticket 1",
      "comment": {
        "body": "First ticket"
      }
    },
    {
      "subject": "Ticket 2",
      "comment": {
        "body": "Second ticket"
      }
    }
  ]
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/create_many.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
批量创建工单：
写入文件
/tmp/zendesk_request.json
：
json
{
  "tickets": [
    {
      "subject": "Ticket 1",
      "comment": {
        "body": "First ticket"
      }
    },
    {
      "subject": "Ticket 2",
      "comment": {
        "body": "Second ticket"
      }
    }
  ]
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/create_many.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

7. List Users

7. 列出用户

Get all users:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email, role}
获取所有用户：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email, role}

8. Get Current User

8. 获取当前用户

Get authenticated user details:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
获取已认证用户的详情：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"

9. Create User

9. 创建用户

Create an end-user:
Write to 
/tmp/zendesk_request.json
:
json
{
  "user": {
    "name": "John Customer",
    "email": "john@example.com",
    "role": "end-user"
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
Create an agent:
Write to 
/tmp/zendesk_request.json
:
json
{
  "user": {
    "name": "Jane Agent",
    "email": "jane@company.com",
    "role": "agent"
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建终端用户：
写入文件
/tmp/zendesk_request.json
：
json
{
  "user": {
    "name": "John Customer",
    "email": "john@example.com",
    "role": "end-user"
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建客服专员：
写入文件
/tmp/zendesk_request.json
：
json
{
  "user": {
    "name": "Jane Agent",
    "email": "jane@company.com",
    "role": "agent"
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

10. Update User

10. 更新用户信息

Update user information:
bash
USER_ID="456"
Write to 
/tmp/zendesk_request.json
:
json
{
  "user": {
    "name": "Updated Name",
    "phone": "+1234567890"
  }
}
Then run:
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/${USER_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
更新用户信息：
bash
USER_ID="456"
写入文件
/tmp/zendesk_request.json
：
json
{
  "user": {
    "name": "Updated Name",
    "phone": "+1234567890"
  }
}
然后运行：
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/${USER_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

11. Search Users

11. 搜索用户

Search for users by query:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/search.json?query=john" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email}
按查询条件搜索用户：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/search.json?query=john" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email}

12. List Organizations

12. 列出组织

Get all organizations:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.organizations[] | {id, name, domain_names}
获取所有组织：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.organizations[] | {id, name, domain_names}

13. Create Organization

13. 创建组织

Create a new organization:
Write to 
/tmp/zendesk_request.json
:
json
{
  "organization": {
    "name": "Acme Inc",
    "domain_names": ["acme.com", "acmeinc.com"],
    "details": "Important customer"
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建新组织：
写入文件
/tmp/zendesk_request.json
：
json
{
  "organization": {
    "name": "Acme Inc",
    "domain_names": ["acme.com", "acmeinc.com"],
    "details": "Important customer"
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

14. Update Organization

14. 更新组织信息

Update organization details:
bash
ORG_ID="789"
Write to 
/tmp/zendesk_request.json
:
json
{
  "organization": {
    "name": "Acme Corporation",
    "notes": "Premium customer since 2020"
  }
}
Then run:
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations/${ORG_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
更新组织详情：
bash
ORG_ID="789"
写入文件
/tmp/zendesk_request.json
：
json
{
  "organization": {
    "name": "Acme Corporation",
    "notes": "Premium customer since 2020"
  }
}
然后运行：
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations/${ORG_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

15. List Groups

15. 列出客服组

Get all agent groups:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.groups[] | {id, name}
获取所有客服组：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.groups[] | {id, name}

16. Create Group

16. 创建客服组

Create a new agent group:
Write to 
/tmp/zendesk_request.json
:
json
{
  "group": {
    "name": "Support Team"
  }
}
Then run:
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
创建新客服组：
写入文件
/tmp/zendesk_request.json
：
json
{
  "group": {
    "name": "Support Team"
  }
}
然后运行：
bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

17. Search API

17. 搜索API

Search for open tickets:
Write to 
/tmp/zendesk_query.txt
:
type:ticket status:open
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[] | {id, subject, status}
Search for high priority tickets:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]
Search tickets with keywords:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]
Search users by email domain:
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]
搜索未关闭的工单：
写入文件
/tmp/zendesk_query.txt
：
type:ticket status:open
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[] | {id, subject, status}
搜索高优先级工单：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]
搜索包含关键词的工单：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]
按邮箱域名搜索用户：
bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[]

18. Get Ticket Comments

18. 获取工单评论

List all comments on a ticket:
bash
TICKET_ID="123"

curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}/comments.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.comments[] | {id, body, author_id, public}
列出工单的所有评论：
bash
TICKET_ID="123"

curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}/comments.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.comments[] | {id, body, author_id, public}

19. Assign Ticket to Group

19. 将工单分配给客服组

Assign a ticket to a group:
bash
TICKET_ID="123"
GROUP_ID="456"
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "group_id": GROUP_ID_PLACEHOLDER
  }
}
Then run:
bash
sed -i '' "s/GROUP_ID_PLACEHOLDER/${GROUP_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
将工单分配给指定客服组：
bash
TICKET_ID="123"
GROUP_ID="456"
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "group_id": GROUP_ID_PLACEHOLDER
  }
}
然后运行：
bash
sed -i '' "s/GROUP_ID_PLACEHOLDER/${GROUP_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

20. Bulk Update Tickets

20. 批量更新工单

Update multiple tickets at once:
Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "status": "solved"
  }
}
Then run:
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/update_many.json?ids=123,124,125" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
一次性更新多个工单：
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "status": "solved"
  }
}
然后运行：
bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/update_many.json?ids=123,124,125" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

Common Workflows

常见工作流

Create Ticket and Assign to Agent

创建工单并分配给客服专员

Write to 
/tmp/zendesk_request.json
:
json
{
  "ticket": {
    "subject": "New issue",
    "comment": {
      "body": "Need help"
    }
  }
}
Then run:
bash
undefined
写入文件
/tmp/zendesk_request.json
：
json
{
  "ticket": {
    "subject": "New issue",
    "comment": {
      "body": "Need help"
    }
  }
}
然后运行：
bash
undefined

Create ticket

创建工单

TICKET_RESPONSE=$(curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json)
TICKET_ID=$(echo $TICKET_RESPONSE | jq -r '.ticket.id')
TICKET_RESPONSE=$(curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json)
TICKET_ID=$(echo $TICKET_RESPONSE | jq -r '.ticket.id')

Assign to agent

分配给客服专员

ASSIGNEE_ID="789"

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER,
    "status": "open"
  }
}
Then run:
bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
ASSIGNEE_ID="789"

写入文件`/tmp/zendesk_request.json`：

```json
{
  "ticket": {
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER,
    "status": "open"
  }
}
然后运行：
bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json

Find and Close Old Tickets

查找并关闭旧工单

bash
undefined
bash
undefined

Search for old open tickets (30+ days)

搜索30天以上的未关闭工单

OLD_TICKETS="$(curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq -r '.results[].id' | paste -sd "," -)"

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "status": "closed"
  }
}
Then run:
bash
undefined
OLD_TICKETS="$(curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq -r '.results[].id' | paste -sd "," -)"

写入文件`/tmp/zendesk_request.json`：

```json
{
  "ticket": {
    "status": "closed"
  }
}
然后运行：
bash
undefined

Bulk close them

批量关闭

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/update_many.json?ids=${OLD_TICKETS}" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
undefined
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/update_many.json?ids=${OLD_TICKETS}" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
undefined

Search Query Syntax

搜索查询语法

Ticket Search Operators

工单搜索操作符

  • type:ticket
    - Search tickets only
  • status:open
    - Filter by status (open, pending, solved, closed)
  • priority:high
    - Filter by priority (low, normal, high, urgent)
  • assignee:name
    - Find tickets assigned to specific agent
  • group:name
    - Find tickets in specific group
  • tags:keyword
    - Search by tag
  • created>2024-01-01
    - Created after date
  • created<30
    - Created in last 30 days
  • "exact phrase"
    - Search exact text
  • type:ticket
    - 仅搜索工单
  • status:open
    - 按状态过滤（open、pending、solved、closed）
  • priority:high
    - 按优先级过滤（low、normal、high、urgent）
  • assignee:name
    - 查找分配给特定客服专员的工单
  • group:name
    - 查找特定客服组的工单
  • tags:keyword
    - 按标签搜索
  • created>2024-01-01
    - 搜索指定日期之后创建的工单
  • created<30
    - 搜索过去30天内创建的工单
  • "exact phrase"
    - 搜索精确文本

User Search Operators

用户搜索操作符

  • type:user
    - Search users only
  • role:agent
    - Filter by role (end-user, agent, admin)
  • email:*@domain.com
    - Search by email domain
  • name:john
    - Search by name
  • type:user
    - 仅搜索用户
  • role:agent
    - 按角色过滤（end-user、agent、admin）
  • email:*@domain.com
    - 按邮箱域名搜索
  • name:john
    - 按姓名搜索

Combining Operators

组合操作符

Use spaces for AND logic:
bash
query=type:ticket status:open priority:high
使用空格表示AND逻辑：
bash
query=type:ticket status:open priority:high

Rate Limits

请求速率限制

PlanRequests/Minute
Team200
Growth400
Professional400
Enterprise700
Enterprise Plus2,500
Special Limits:
  • Update Ticket: 30 updates per 10 minutes per user per ticket
  • Account-wide ceiling: 100,000 requests/minute
套餐每分钟请求数
Team200
Growth400
Professional400
Enterprise700
Enterprise Plus2,500
特殊限制:
  • 更新工单：每个用户对每个工单每10分钟最多30次更新
  • 账户全局上限：每分钟100,000次请求

Rate Limit Headers

速率限制响应头

X-Rate-Limit: 700                    # Your account's limit
X-Rate-Limit-Remaining: 685          # Requests remaining
Retry-After: 45                      # Seconds to wait if exceeded
X-Rate-Limit: 700                    # 您的账户限制
X-Rate-Limit-Remaining: 685          # 剩余请求数
Retry-After: 45                      # 超出限制后需等待的秒数

Handling Rate Limits

处理速率限制

bash
undefined
bash
undefined

Use curl retry flags

使用curl重试标志

curl "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json"
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
--retry 3 --retry-delay 5
undefined
curl "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json"
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
--retry 3 --retry-delay 5
undefined

Guidelines

指南

  1. Enable API token access first: In Admin Center, ensure Token Access is enabled before using tokens
  2. Always use HTTPS: TLS 1.2+ required
  3. Monitor rate limits: Check 
    X-Rate-Limit-Remaining
    header
  4. Use bulk operations: 
    create_many
    , 
    update_many
    endpoints save API calls
  5. Implement exponential backoff: Honor 
    Retry-After
    header on 429 responses
  6. Paginate large datasets: Default limit is 100, max per_page is 100
  7. Secure your tokens: Store in environment variables, never in code
  8. Use specific searches: Narrow queries with filters to reduce response size
  9. Verify with reliable endpoints: Use 
    /tickets.json
    or 
    /users.json
    to test tokens (not 
    /users/me.json
    )
  10. Status values: open, pending, hold, solved, closed
  11. Priority values: low, normal, high, urgent
  12. User roles: end-user, agent, admin (need agent or admin role for API access)
  13. Ticket types: problem, incident, question, task
  14. Authentication format: email/token:api_token (curl -u handles encoding)
  15. New workspaces: Fresh Zendesk accounts come with sample tickets for testing
  1. 先启用API Token访问：在管理中心，使用Token前确保已启用Token访问
  2. 始终使用HTTPS：要求TLS 1.2+版本
  3. 监控速率限制：检查
    X-Rate-Limit-Remaining
    响应头
  4. 使用批量操作：
    create_many
    、
    update_many
    端点可减少API调用次数
  5. 实现指数退避：收到429响应时遵循
    Retry-After
    头的指示
  6. 对大型数据集分页：默认限制为100，最大每页100条
  7. 妥善保管Token：存储在环境变量中，切勿写入代码
  8. 使用精准搜索：通过过滤器缩小查询范围以减少响应数据量
  9. 使用可靠端点验证：使用
    /tickets.json
    或
    /users.json
    测试Token（不要用
    /users/me.json
    ）
  10. 状态值：open、pending、hold、solved、closed
  11. 优先级值：low、normal、high、urgent
  12. 用户角色：end-user、agent、admin（需要agent或admin角色才能访问API）
  13. 工单类型：problem、incident、question、task
  14. 身份验证格式：email/token:api_token（curl的-u参数会处理编码）
  15. 新工作区：全新Zendesk账户会提供示例工单用于测试

API Reference

API参考