---
title: "Freshdesk 커넥터"
description: "Tajo를 통해 Freshdesk의 지원 티켓, 연락처, 상담원 데이터를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/support/freshdesk/
markdown: https://tajo.io/kr/docs/connectors/support/freshdesk.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. 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 |
| **카테고리** | Support |
| **설정 복잡도** | 쉬움 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 티켓, 연락처, 상담원, 회사 |
| **사용 가능한 스킬** | 6 |

## 기능

- **연락처 동기화** - Freshdesk 연락처를 Brevo 연락처 목록으로 양방향 동기화
- **티켓 이벤트 추적** - 티켓 생성, 업데이트, 해결 이벤트를 Brevo로 전달
- **CSAT 동기화** - 고객 만족도 점수를 Brevo 연락처 속성으로 동기화
- **회사 동기화** - Freshdesk 회사를 Brevo 연락처 세그먼테이션에 매핑
- **상담원 데이터** - 내부 워크플로 자동화를 위한 상담원 할당 추적
- **맞춤 필드** - Freshdesk 맞춤 티켓 및 연락처 필드를 Brevo 속성에 매핑

## 사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. 관리자 접근 권한이 있는 Freshdesk 계정
2. Freshdesk API Key (프로필 설정에서 확인 가능)
3. Freshdesk 도메인 (예: `yourcompany.freshdesk.com`)
4. API 접근이 가능한 Brevo 계정
5. API 자격 증명이 있는 Tajo 계정

## 인증

### API 키 인증

Freshdesk는 HTTP Basic Auth를 통한 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. **Profile Settings**로 이동
4. API Key가 오른쪽에 표시됨

## 구성

### 기본 설정

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

    # 데이터 동기화 옵션
    sync:
      contacts: true
      tickets: true
      companies: true
      satisfaction_ratings: true

    # Brevo 목록 할당
    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

  # 지원 지표
  total_tickets: TICKET_COUNT
  open_tickets: OPEN_TICKETS
  avg_csat: CSAT_SCORE
  last_ticket_date: LAST_SUPPORT_DATE

  # 맞춤 필드
  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
});

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

### 연락처를 Brevo로 동기화

```javascript
// Freshdesk 연락처를 가져와서 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();
// 각 연락처:
// {
//   "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
// 티켓 이벤트를 전달하도록 Freshdesk 웹훅 설정
// Freshdesk Admin > Automations > Webhook에서 구성

// 웹훅 핸들러
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
// 특정 고객의 모든 티켓 검색
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 요청/분 | Starter 요금제 |
| **Garden** | 400 요청/분 | Growth 요금제 |
| **Estate** | 700 요청/분 | Pro 요금제 |
| **Forest** | 1,000 요청/분 | Enterprise 요금제 |

추가 제한:

| 리소스 | 제한 |
| --- | --- |
| **목록 엔드포인트** | 쿼리당 30 페이지 |
| **페이지당** | 최대 100 레코드 |
| **Search API** | 2 요청/초 |
| **Bulk 작업** | 요청당 10 레코드 |

속도 제한 헤더

Freshdesk는 응답 헤더에 속도 제한 정보를 반환합니다. `X-RateLimit-Remaining`을 모니터링하고 제한에 접근할 때 백오프를 구현하십시오.

## 문제 해결

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| `401 Unauthorized` | 잘못된 API 키 | Freshdesk 프로필 설정에서 API 키 확인 |
| `403 Forbidden` | 권한 부족 | API 키가 관리자 계정에 속하는지 확인 |
| 연락처가 동기화되지 않음 | 이메일 필드 누락 | Freshdesk 연락처에는 이메일 주소가 필요함 |
| 티켓이 표시되지 않음 | 잘못된 도메인 | Freshdesk 도메인 URL이 올바른지 확인 |
| 검색이 비어 있음 | 쿼리 구문 오류 | 큰따옴표가 있는 Freshdesk 검색 쿼리 구문 사용 |
| `429 Too Many Requests` | 속도 제한 초과 | 요금제 티어 기반 속도 제한 구현 |
| 맞춤 필드 누락 | 필드가 활성화되지 않음 | Freshdesk 관리자에서 맞춤 필드가 활성화되어 있는지 확인 |

## 모범 사례

1. **실시간 동기화에 웹훅 사용** - 티켓 이벤트에서 웹훅을 트리거하도록 Freshdesk Automations 구성
2. **CSAT 점수 동기화** - 세그먼테이션을 위해 고객 만족도 평가를 Brevo 속성으로 추적
3. **티켓 상태를 목록에 매핑** - 티켓 상태에 따라 Brevo 목록 간에 연락처 자동 이동
4. **지원 지표 추적** - 연락처당 티켓 수, 평균 응답 시간, 해결률 동기화
5. **Search API를 신중하게 사용** - Search API는 엄격한 속도 제한이 있음; 가능한 경우 결과 캐싱
6. **대량 내보내기 페이지네이션** - 초기 동기화에 `page` 및 `per_page` 매개변수로 페이지네이션 사용

## 보안

- **API 키 인증** - API 키를 사용한 간단한 HTTP Basic Auth
- **HTTPS 전용** - 모든 API 통신에 TLS 암호화 필요
- **IP 허용 목록** - Estate 및 Forest 요금제에서 사용 가능
- **역할 기반 접근** - 상담원 역할에 연결된 API 키 권한
- **SOC 2 Type II** - Freshdesk는 SOC 2 Type II 인증을 받음
- **GDPR 준수** - 데이터 내보내기 및 삭제 요청 지원

## 관련 리소스

- [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)
- [Shopify 커넥터](https://tajo.io/kr/docs/connectors/ecommerce/shopify)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)