---
title: "Freshdesk 连接器"
description: "完整的 Freshdesk 集成指南，通过 Tajo 将支持工单、联系人和客服数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/support/freshdesk/
markdown: https://tajo.io/zh-cn/docs/connectors/support/freshdesk.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Freshdesk 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 Tajo 将 Freshdesk 连接到 Brevo，统一支持和营销数据。同步客户支持工单、联系人档案和满意度评分，基于支持互动触发精准沟通。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Freshdesk |
| **类别** | 支持 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 工单、联系人、客服、公司 |
| **可用技能** | 6 |

## 功能

- **联系人同步** - Freshdesk 联系人与 Brevo 联系人列表的双向同步
- **工单事件跟踪** - 将工单创建、更新和解决事件转发到 Brevo
- **CSAT 同步** - 将客户满意度评分同步为 Brevo 联系人属性
- **公司同步** - 将 Freshdesk 公司映射到 Brevo 联系人细分
- **客服数据** - 跟踪客服分配，用于内部工作流自动化
- **自定义字段** - 将 Freshdesk 自定义工单和联系人字段映射到 Brevo 属性

## 前提条件

开始之前，请确保您已具备：

1. 具有管理员访问权限的 Freshdesk 账户
2. 您的 Freshdesk API 密钥（在”个人资料设置”中找到）
3. 您的 Freshdesk 域名（例如 `yourcompany.freshdesk.com`）
4. 具有 API 访问权限的 Brevo 账户
5. 具有 API 凭据的 Tajo 账户

## 认证

### API 密钥认证

Freshdesk 通过 HTTP 基本认证使用 API 密钥。API 密钥作为用户名，任意字符串（通常为 `X`）作为密码。

```bash
curl -u "YOUR_API_KEY:X" \
  https://yourcompany.freshdesk.com/api/v2/tickets
```

或在 Authorization 请求头中使用 Base64 编码：

```bash
curl https://yourcompany.freshdesk.com/api/v2/tickets \
  -H "Authorization: Basic BASE64_ENCODED_API_KEY:X" \
  -H "Content-Type: application/json"
```

### 查找您的 API 密钥

1. 登录您的 Freshdesk 账户
2. 点击右上角的个人头像
3. 前往**个人资料设置**
4. 您的 API 密钥显示在右侧

## 配置

### 基础设置

```yaml
connectors:
  freshdesk:
    enabled: true
    domain: "yourcompany.freshdesk.com"
    api_key: "your-freshdesk-api-key"

    # Data sync options
    sync:
      contacts: true
      tickets: true
      companies: true
      satisfaction_ratings: true

    # Brevo list assignment
    lists:
      all_support_contacts: 30
      open_tickets: 31
      resolved_tickets: 32
```

### 联系人字段映射

将 Freshdesk 联系人字段映射到 Brevo 属性：

```yaml
contact_mapping:
  email: email
  name: FULLNAME
  phone: SMS
  company_id: COMPANY
  job_title: JOB_TITLE
  twitter_id: TWITTER
  language: LANGUAGE
  time_zone: TIMEZONE

  # Support metrics
  total_tickets: TICKET_COUNT
  open_tickets: OPEN_TICKETS
  avg_csat: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # Custom fields
  custom_fields.account_type: ACCOUNT_TYPE
  custom_fields.subscription_tier: PLAN
```

### 工单事件映射

将 Freshdesk 工单事件映射到 Brevo 自动化触发器：

```yaml
ticket_events:
  ticket_created: "support_ticket_created"
  ticket_updated: "support_ticket_updated"
  ticket_resolved: "support_ticket_resolved"
  ticket_closed: "support_ticket_closed"
  ticket_reopened: "support_ticket_reopened"
  satisfaction_rated: "csat_submitted"
  note_added: "support_note_added"
```

## API 端点

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/api/v2/tickets` | 列出所有工单 |
| `POST` | `/api/v2/tickets` | 创建工单 |
| `GET` | `/api/v2/tickets/{id}` | 获取特定工单 |
| `PUT` | `/api/v2/tickets/{id}` | 更新工单 |
| `DELETE` | `/api/v2/tickets/{id}` | 删除工单 |
| `GET` | `/api/v2/contacts` | 列出所有联系人 |
| `POST` | `/api/v2/contacts` | 创建联系人 |
| `PUT` | `/api/v2/contacts/{id}` | 更新联系人 |
| `GET` | `/api/v2/companies` | 列出所有公司 |
| `GET` | `/api/v2/agents` | 列出所有客服 |
| `GET` | `/api/v2/surveys/satisfaction_ratings` | 列出 CSAT 评分 |
| `GET` | `/api/v2/search/tickets?query=` | 搜索工单 |

## 代码示例

### 初始化 Freshdesk 连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Freshdesk account
await tajo.connectors.connect('freshdesk', {
  domain: 'yourcompany.freshdesk.com',
  apiKey: process.env.FRESHDESK_API_KEY
});
```

### 将联系人同步到 Brevo

```javascript
// Fetch Freshdesk contacts and sync to Brevo
const response = await fetch(
  'https://yourcompany.freshdesk.com/api/v2/contacts?page=1&per_page=100',
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`),
      'Content-Type': 'application/json'
    }
  }
);

const contacts = await response.json();
// Each contact:
// {
//   "id": 12345,
//   "name": "Jane Kim",
//   "email": "jane@example.com",
//   "phone": "+15551234567",
//   "company_id": 678,
//   "job_title": "Product Manager",
//   "created_at": "2024-01-15T10:30:00Z"
// }
```

### 跟踪工单事件

```javascript
// Set up Freshdesk webhook to forward ticket events
// Configure in Freshdesk Admin > Automations > Webhook

// Webhook handler
app.post('/webhooks/freshdesk', async (req, res) => {
  const { ticket, event_type } = req.body;

  await tajo.connectors.handleWebhook('freshdesk', {
    topic: event_type,
    payload: {
      ticketId: ticket.id,
      subject: ticket.subject,
      status: ticket.status,
      priority: ticket.priority,
      requesterEmail: ticket.requester.email,
      createdAt: ticket.created_at
    }
  });

  res.status(200).send('OK');
});
```

### 按客户搜索工单

```javascript
// Search for all tickets from a specific customer
const query = encodeURIComponent('"email:jane@example.com"');
const response = await fetch(
  `https://yourcompany.freshdesk.com/api/v2/search/tickets?query=${query}`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${API_KEY}:X`)
    }
  }
);

const { results, total } = await response.json();
```

## 速率限制

| 计划 | 限制 | 详情 |
| --- | --- | --- |
| **Sprout** | 50 请求/分钟 | 免费计划 |
| **Blossom** | 200 请求/分钟 | 入门计划 |
| **Garden** | 400 请求/分钟 | 增长计划 |
| **Estate** | 700 请求/分钟 | 专业计划 |
| **Forest** | 1,000 请求/分钟 | 企业计划 |

附加限制：

| 资源 | 限制 |
| --- | --- |
| **列表端点** | 每次查询 30 页 |
| **每页** | 最多 100 条记录 |
| **搜索 API** | 2 请求/秒 |
| **批量操作** | 每次请求 10 条记录 |

速率限制响应头

Freshdesk 在响应头中返回速率限制信息。监控 `X-RateLimit-Remaining`，在接近限制时实施退避策略。

## 故障排除

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| `401 Unauthorized` | API 密钥无效 | 在 Freshdesk 个人资料设置中验证 API 密钥 |
| `403 Forbidden` | 权限不足 | 确保 API 密钥属于管理员账户 |
| 联系人未同步 | 缺少邮箱字段 | Freshdesk 联系人需要邮箱地址 |
| 工单未显示 | 域名错误 | 验证 Freshdesk 域名 URL 是否正确 |
| 搜索返回空 | 查询语法错误 | 使用带双引号的 Freshdesk 搜索查询语法 |
| `429 Too Many Requests` | 超出速率限制 | 根据计划层级实施速率限制 |
| 自定义字段缺失 | 字段未启用 | 确保在 Freshdesk 管理中启用自定义字段 |

## 最佳实践

1. **使用 Webhook 进行实时同步** - 配置 Freshdesk 自动化，在工单事件时触发 Webhook
2. **同步 CSAT 评分** - 将客户满意度评分作为 Brevo 属性跟踪，用于细分
3. **将工单状态映射到列表** - 根据工单状态自动在 Brevo 列表间移动联系人
4. **跟踪支持指标** - 同步每个联系人的工单数量、平均响应时间和解决率
5. **谨慎使用搜索 API** - 搜索 API 有更严格的速率限制；尽可能缓存结果
6. **分页处理大型导出** - 初始同步时使用 `page` 和 `per_page` 参数进行分页

## 安全

- **API 密钥认证** - 使用 API 密钥的简单 HTTP 基本认证
- **仅 HTTPS** - 所有 API 通信均需要 TLS 加密
- **IP 白名单** - Estate 和 Forest 计划可用
- **基于角色的访问** - API 密钥权限与客服角色绑定
- **SOC 2 Type II** - Freshdesk 通过 SOC 2 Type II 认证
- **GDPR 合规** - 支持数据导出和删除请求

## 相关资源

- [Brevo 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/brevo)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Shopify 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)