用途:面向 Zendesk 客户支持场景,通过 REST API 管理支持工单(support ticket)与客服数据。
主要能力:
- 工单:列出、获取、创建、更新、删除单张工单,支持 create_many 批量创建与 update_many 批量更新,可设置主题、评论、优先级、状态、类型、标签、受理人与所属群组。
- 用户:列出、创建(终端用户/客服/管理员)、更新、按查询搜索,以及获取当前认证用户 /users/me.json。
- 组织与群组:列出、创建、更新组织;列出与创建客服群组。
- 搜索:使用 /search.json 及操作符查询工单与用户。
- 工单评论:列出某工单的全部评论。
使用方式: 基础 URL 为 https://{subdomain}.zendesk.com/api/v2/;认证使用 API Token,curl 通过 -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" 传递(-u 会自动做 Base64 编码)。示例命令如: curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" POST/PUT 请求将 JSON 写入 /tmp/zendesk_request.json,再用 -d @/tmp/zendesk_request.json 发送。排障可运行 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。
搜索语法要点:type:ticket、status:open、priority:high、assignee:name、group:name、tags:keyword、created>2024-01-01、created<30、精确短语;用户侧支持 type:user、role:agent、email:*@domain.com、name:john;空格表示 AND 逻辑。
限制与注意事项:需先在 Admin Center 启用 Token Access;必须使用 HTTPS(TLS 1.2+);关注 X-Rate-Limit-Remaining 与 429 的 Retry-After,建议指数退避;分页默认 100、per_page 最大 100;更新工单存在每用户每工单 10 分钟 30 次的上限,账户级上限 100,000 请求/分钟。状态值为 open、pending、hold、solved、closed;优先级为 low、normal、high、urgent;用户角色为 end-user、agent、admin。API 参考:https://developer.zendesk.com/api-reference/。