freshdesk-api

Freshdesk API

概述

使用 Freshdesk 的 REST API v2，为其帮助台平台构建集成。管理支持工单、联系人、公司、客服人员，并自动化工作流。该 API 支持对所有主要资源执行完整的 CRUD 操作，并提供筛选、分页和嵌入数据功能。

适用场景

• 构建帮助台集成或支持仪表板
• 提取和分析支持工单数据
• 自动化工单路由、分配或更新
• 与 CRM 系统同步联系人/公司
• 创建支持指标自定义报告
• 实现聊天机器人或 AI 支持工具
• 向 Freshdesk 迁移数据，或从 Freshdesk 迁出数据

前置条件

API 密钥设置

1. 以管理员身份登录 Freshdesk
2. 点击个人资料图片 → 个人资料设置
3. 在右侧边栏找到你的 API 密钥
4. 安全存储（切勿提交到版本控制系统）

# Set environment variable
export FRESHDESK_API_KEY="your-api-key-here"
export FRESHDESK_DOMAIN="yourcompany"  # From yourcompany.freshdesk.com

所需工具

• 用于 HTTP 请求的 curl
• 用于解析 JSON 的 jq（macOS 上运行 brew install jq）
• 使用 SDK 时：Python 3.6+、Node.js 14+ 或 Ruby 2.7+

API 基础 URL

https://{domain}.freshdesk.com/api/v2/

将 {domain} 替换为你的 Freshdesk 子域名（例如，acme.freshdesk.com 中的 acme）。

身份验证

Freshdesk 使用 HTTP Basic Authentication，将你的 API 密钥作为用户名，X 作为密码。

curl 示例

# Using -u flag (username:password)
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

# Using Authorization header
curl -H "Authorization: Basic $(echo -n "$FRESHDESK_API_KEY:X" | base64)" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

请求头

始终包含：

Content-Type: application/json

快速开始

获取所有工单

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

创建工单

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "subject": "Support needed",
    "description": "Details of the issue...",
    "email": "[email protected]",
    "priority": 2,
    "status": 2
  }' \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

获取联系人

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts/12345"

搜索工单

# Search by status and priority
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:2 AND priority:3\""

核心端点

端点	描述
/tickets	创建、列出、更新和删除工单
/contacts	管理客户联系人
/companies	管理公司/组织记录
/agents	查看和管理支持客服人员
/groups	管理客服人员组
/conversations	工单回复、备注和转发
/time_entries	跟踪工单处理时间
/surveys/satisfaction_ratings	客户满意度数据
/products	产品目录管理
/business_hours	营业时间配置
/email_configs	电子邮件设置
/sla_policies	SLA 策略管理
/canned_responses	预设回复模板
/ticket_fields	自定义工单字段

请参阅 references/tickets-api.md，了解详细的工单操作。 请参阅 references/contacts-companies.md，了解联系人/公司管理。

速率限制

按 API 版本划分的限制

版本	限制
API v1	每小时 1000 次调用
API v2	按分钟限制，具体取决于套餐
试用套餐	每分钟 50 次调用

速率限制请求头

每个响应都包含：

请求头	描述
X-Ratelimit-Total	每分钟允许的总调用次数
X-Ratelimit-Remaining	本分钟剩余调用次数
X-Ratelimit-Used-CurrentRequest	此请求消耗的额度

处理速率限制

#!/usr/bin/env bash
# Retry with exponential backoff for 429 errors

max_retries=3
retry_count=0

while [ "$retry_count" -lt "$max_retries" ]; do
  response=$(curl -s -w "\n%{http_code}" -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets")

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  if [ "$http_code" = "200" ]; then
    echo "$body"
    exit 0
  elif [ "$http_code" = "429" ]; then
    delay=$((2 ** retry_count))
    echo "Rate limited. Retrying in ${delay}s..." >&2
    sleep "$delay"
    retry_count=$((retry_count + 1))
  else
    echo "Error: HTTP $http_code" >&2
    echo "$body" >&2
    exit 1
  fi
done

echo "Max retries exceeded" >&2
exit 1

额度系统

某些操作会消耗多个 API 额度：

• 基本请求：1 个额度
• 包含嵌入数据（include= 参数）：每个 include 增加 1 个额度
• 示例：?include=requester,company 总共消耗 3 个额度

分页

查询参数

参数	默认值	最大值	描述
page	1	-	页码（从 1 开始）
per_page	30	100	每页结果数

示例：遍历所有工单

page=1
while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100")

  count=$(echo "$response" | jq length)

  if [ "$count" -eq 0 ]; then
    break
  fi

  echo "$response" | jq '.[] | {id, subject, status}'
  page=$((page + 1))
done

Link 请求头

响应中包含用于导航的 Link 请求头：

Link: <https://domain.freshdesk.com/api/v2/tickets?page=2>; rel="next"

筛选和嵌入

筛选参数

列表端点常用的筛选参数：

参数	示例	描述
filter	new_and_my_open	预定义筛选条件
requester_id	12345	按请求者筛选
company_id	67890	按公司筛选
updated_since	2024-01-01T00:00:00Z	筛选指定日期之后修改的记录

预定义工单筛选条件

# New and open tickets assigned to me
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=new_and_my_open"

# All unresolved tickets
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=all_unresolved"

# Tickets updated in last 30 days
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2024-11-01T00:00:00Z"

包含（嵌入相关数据）

嵌入相关对象，以减少 API 调用：

# Include requester and company with ticket
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/123?include=requester,company"

# Include stats with ticket list
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?include=stats"

工单可用的包含项：requester、company、stats、conversations、description

搜索 API

搜索 API 支持对工单、联系人和公司执行复杂查询。

语法

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"<query>\""

查询示例

# Tickets with specific status and priority
"status:2 AND priority:3"

# Tickets from a specific requester
"requester_email:'[email protected]'"

# Tickets created in date range
"created_at:>'2024-01-01' AND created_at:<'2024-02-01'"

# Tickets with specific tag
"tag:'urgent'"

# Tickets assigned to specific agent
"agent_id:12345"

# Full-text search in subject and description
"~'password reset'"

搜索运算符

运算符	描述
AND	两个条件都必须匹配
OR	任一条件匹配
:	等于
:>	大于
:<	小于
~	全文搜索

工单状态和优先级值

状态

值	状态
2	开放
3	待处理
4	已解决
5	已关闭

优先级

值	优先级
1	低
2	中
3	高
4	紧急

来源

值	来源
1	电子邮件
2	门户
3	电话
7	聊天
8	Mobihelp
9	反馈小组件
10	外发电子邮件

错误处理

HTTP 状态码

代码	含义	操作
200	成功	处理响应
201	已创建	资源已成功创建
204	无内容	删除成功
400	错误请求	检查请求正文/参数
401	未授权	验证 API 密钥
403	禁止访问	检查权限
404	未找到	验证资源 ID
409	冲突	资源已存在
429	请求过多	等待后重试
500	服务器错误	采用退避策略重试

错误响应格式

{
  "description": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "It should be a valid email address.",
      "code": "invalid_value"
    }
  ]
}

Webhook

Freshdesk 可在工单事件发生时发送 Webhook 通知。在“管理 → 自动化 → Webhook”中配置 Webhook。

事件类型

• 工单已创建
• 工单已更新
• Agent 回复
• 客户回复
• 已添加备注
• 工单已解决/关闭

Webhook 负载示例

{
  "freshdesk_webhook": {
    "ticket_id": 12345,
    "ticket_subject": "Support needed",
    "ticket_status": "Open",
    "ticket_priority": "Medium",
    "ticket_requester_email": "[email protected]",
    "triggered_event": "ticket_created"
  }
}

详细的 Webhook 设置说明请参阅 references/webhooks-automation.md。

最佳实践

性能

1. 使用 Webhook 代替轮询 - 实时响应事件
2. 批量操作 - 在可用时使用批量端点
3. 缓存静态数据 - Agent 列表和工单字段很少变化
4. 使用 include 参数 - 通过嵌入数据减少 API 调用
5. 高效分页 - 批量操作时将 per_page=100 设为最大值

安全

1. 将 API 密钥存储在环境变量中 - 切勿硬编码
2. 仅使用 HTTPS - 所有 API 调用都必须使用 HTTPS
3. 定期轮换密钥 - 每 90 天重新生成 API 密钥
4. 限制 API 密钥范围 - 使用权限最少的 Agent 账户

可靠性

1. 实现带退避的重试 - 处理 429 和 5xx 错误
2. 检查速率限制标头 - 达到限制前暂停
3. 验证响应 - 检查是否存在错误对象
4. 记录 API 调用 - 跟踪使用情况并调试问题

数据处理

1. 处理 null 字段 - API 返回 null 值，而不是省略字段
2. 将时间戳解析为 UTC - 格式：YYYY-MM-DDTHH:MM:SSZ
3. 验证自定义字段 - 提交前检查字段类型
4. 清理用户输入 - 防止描述中出现注入

SDK 和库

官方/社区 SDK

语言	软件包	安装
Python	python-freshdesk	pip install python-freshdesk
Node.js	node-freshdesk-api	npm install node-freshdesk-api
Ruby	freshdesk-ruby	gem install freshdesk
PHP	官方示例	请参阅 Freshdesk 文档
Java	官方示例	请参阅 Freshdesk 文档

详细的代码示例请参阅 references/sdk-examples.md。

常见工作流

将所有工单导出为 JSON

#!/usr/bin/env bash
# Export all tickets to tickets.json

page=1
echo "[" > tickets.json
first=true

while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100&include=description")

  count=$(echo "$response" | jq length)
  [ "$count" -eq 0 ] && break

  if [ "$first" = true ]; then
    first=false
  else
    echo "," >> tickets.json
  fi

  echo "$response" | jq '.[]' | paste -sd ',' - >> tickets.json
  page=$((page + 1))
  sleep 0.5  # Respect rate limits
done

echo "]" >> tickets.json
echo "Exported $((page - 1)) pages of tickets"

从 CSV 同步联系人

#!/usr/bin/env bash
# Import contacts from contacts.csv (name,email,company_id)

while IFS=, read -r name email company_id; do
  curl -s -u "$FRESHDESK_API_KEY:X" \
    -H "Content-Type: application/json" \
    -X POST \
    -d "{\"name\":\"$name\",\"email\":\"$email\",\"company_id\":$company_id}" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts"
  sleep 0.5
done < contacts.csv

获取工单指标

# Get resolution time stats for closed tickets this month
curl -s -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:5 AND created_at:>'2024-12-01'\"" \
  | jq '[.results[] | .stats.resolved_at as $r | .created_at as $c |
    (($r | fromdateiso8601) - ($c | fromdateiso8601)) / 3600] |
    {count: length, avg_hours: (add / length)}'

资源

• Freshdesk API 文档
• API v2 参考
• Webhooks 指南
• 速率限制常见问题
• Python SDK
• Node.js SDK
• Ruby SDK

参考文件

如需详细的端点文档：

• 工单 API 参考 - 完整的工单 CRUD、对话和时间记录
• 联系人与公司 - 联系人和公司管理
• Webhooks 与自动化 - Webhook 设置和自动化规则
• SDK 代码示例 - Python、Node.js 和 Ruby 示例