---
title: "ActiveCampaign 커넥터"
description: "Tajo를 통해 ActiveCampaign의 연락처, 거래, 자동화, 참여 이벤트를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/marketing/activecampaign/
markdown: https://tajo.io/kr/docs/connectors/marketing/activecampaign.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# ActiveCampaign 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

ActiveCampaign 계정을 Tajo를 통해 Brevo에 연결하여 포괄적인 연락처 마이그레이션, 거래 파이프라인 동기화, 자동화 매핑, 두 플랫폼 간의 통합된 마케팅 데이터를 구현하십시오.

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | ActiveCampaign |
| **카테고리** | Marketing |
| **설정 복잡도** | 중간 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 연락처, 거래, 자동화, 이벤트 |
| **API Base URL** | `https://{account}.api-us1.com/api/3` |

## 기능

- **연락처 마이그레이션** - 맞춤 필드, 태그, 목록 멤버십이 포함된 연락처 마이그레이션
- **거래 파이프라인 동기화** - 매출 추적을 위한 거래 단계, 값, 소유자 동기화
- **자동화 매핑** - ActiveCampaign 자동화를 Brevo 워크플로 트리거에 매핑
- **이벤트 추적** - 행동 세그먼테이션을 위한 사이트 추적 및 맞춤 이벤트 동기화
- **목록 및 태그 동기화** - Brevo에서 목록 구조 및 태그 기반 세그먼트 복제
- **이커머스 통합** - Deep Data(주문, 고객, 카트)를 Brevo에 동기화
- **맞춤 객체 동기화** - ActiveCampaign 맞춤 객체를 Brevo 속성에 매핑
- **점수 동기화** - 리드 및 연락처 점수를 Brevo 속성으로 전송

## 사전 요구 사항

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

1. ActiveCampaign 계정 (Lite, Plus, Professional 또는 Enterprise)
2. Settings > Developer의 API URL 및 API 키
3. API 접근이 가능한 Brevo 계정
4. Tajo 계정

## 인증

### API 키 인증

ActiveCampaign은 헤더 또는 쿼리 매개변수로 전달되는 API 키를 사용합니다.

```bash
curl "https://{account}.api-us1.com/api/3/contacts" \
  -H "Api-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

ActiveCampaign Settings > Developer에서 API URL과 키를 찾으십시오.

API URL

API URL은 계정마다 고유합니다(예: `https://yourcompany.api-us1.com`). 대시보드 URL이 아닌 이 URL을 항상 사용하십시오.

## 구성

### 기본 설정

```yaml
connectors:
  activecampaign:
    enabled: true
    api_url: "https://yourcompany.api-us1.com"
    api_key: "${AC_API_KEY}"

    # 데이터 동기화 옵션
    sync:
      contacts: true
      deals: true
      automations: true
      events: true
      ecommerce: true

    # Brevo로의 목록 매핑
    list_mapping:
      "Main List": 50
      "Newsletter": 51
      "Customers": 52
```

### 필드 매핑

ActiveCampaign 필드를 Brevo 연락처 속성에 매핑합니다.

#### 기본 매핑

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | 연락처 이메일 (고유 식별자) |
| `firstName` optional | string | FIRSTNAME 속성에 매핑 |
| `lastName` optional | string | LASTNAME 속성에 매핑 |
| `phone` optional | string | SMS 속성에 매핑 |
| `tags` optional | array | 세그먼테이션을 위한 연락처 태그 |
| `score` optional | integer | 연락처 참여 점수 |
| `deals` optional | array | 연결된 거래 레코드 |
| `fieldValues` optional | array | 맞춤 필드 값 |

#### 맞춤 필드 매핑

```yaml
field_mapping:
  # 표준 필드
  email: email
  firstName: FIRSTNAME
  lastName: LASTNAME
  phone: SMS

  # 참여 필드
  score: LEAD_SCORE
  rating: ENGAGEMENT_RATING

  # 거래 필드
  deals.value: DEAL_VALUE
  deals.stage: DEAL_STAGE
  deals.owner: DEAL_OWNER

  # 맞춤 필드
  fieldValues.company: COMPANY_NAME
  fieldValues.industry: INDUSTRY
  fieldValues.plan_tier: PLAN_TIER
```

## API 엔드포인트

### 연락처

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/api/3/contacts` | 모든 연락처 목록 |
| `POST` | `/api/3/contacts` | 연락처 생성 |
| `PUT` | `/api/3/contacts/{id}` | 연락처 업데이트 |
| `GET` | `/api/3/contacts/{id}` | 연락처 가져오기 |
| `POST` | `/api/3/contact/sync` | 연락처 동기화 (생성 또는 업데이트) |
| `POST` | `/api/3/import/bulk_import` | 연락처 대량 가져오기 |

### 거래

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/api/3/deals` | 모든 거래 목록 |
| `POST` | `/api/3/deals` | 거래 생성 |
| `PUT` | `/api/3/deals/{id}` | 거래 업데이트 |
| `GET` | `/api/3/dealStages` | 모든 거래 단계 목록 |
| `GET` | `/api/3/dealPipelines` | 모든 파이프라인 목록 |

### 자동화

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/api/3/automations` | 자동화 목록 |
| `GET` | `/api/3/automations/{id}` | 자동화 가져오기 |
| `POST` | `/api/3/contactAutomations` | 자동화에 연락처 추가 |

### 이커머스 (Deep Data)

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `POST` | `/api/3/ecomOrders` | 주문 생성 |
| `GET` | `/api/3/ecomOrders` | 주문 목록 |
| `POST` | `/api/3/ecomCustomers` | 고객 생성 |
| `GET` | `/api/3/ecomCustomers` | 고객 목록 |

### 이벤트 추적

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `POST` | `/api/3/tracking/event` | 맞춤 이벤트 추적 |
| `GET` | `/api/3/eventTrackingEvents` | 모든 이벤트 이름 목록 |
| `POST` | `/api/3/eventTrackingEvents` | 이벤트 이름 생성 |

## 이벤트

### 연락처 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `contact_add` | 새 연락처 생성 | 환영 플로 |
| `contact_update` | 연락처 데이터 변경 | 속성 동기화 |
| `contact_tag_added` | 태그 할당됨 | 세그먼트 업데이트 |
| `contact_tag_removed` | 태그 제거됨 | 세그먼트 정리 |

### 거래 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `deal_add` | 새 거래 생성 | 영업 알림 |
| `deal_update` | 거래 단계 변경 | 파이프라인 자동화 |
| `deal_tasktype_add` | 거래에 작업 추가 | 활동 추적 |

### 자동화 이벤트

| 이벤트 | 트리거 | 사용 사례 |
| --- | --- | --- |
| `automation_contact_add` | 연락처가 자동화에 진입 | 플로 추적 |
| `automation_contact_complete` | 연락처가 자동화 완료 | 다음 단계 트리거 |

## 코드 예제

### 커넥터 초기화

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

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

// ActiveCampaign 연결
await tajo.connectors.connect('activecampaign', {
  apiUrl: process.env.AC_API_URL,
  apiKey: process.env.AC_API_KEY
});
```

### 연락처를 Brevo로 마이그레이션

```javascript
// 맞춤 필드 및 태그가 포함된 전체 연락처 마이그레이션
await tajo.connectors.sync('activecampaign', {
  type: 'full',
  resources: ['contacts', 'deals', 'events'],
  options: {
    includeTags: true,
    includeCustomFields: true,
    includeScores: true,
    includeListMemberships: true
  }
});

// 동기화 상태 확인
const status = await tajo.connectors.status('activecampaign');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 28000,
//   dealsSynced: 4500,
//   eventsSynced: 120000
// }
```

### 맞춤 이벤트 추적

```javascript
// ActiveCampaign 이벤트를 Brevo로 전달
await tajo.activecampaign.trackEvent({
  email: 'customer@example.com',
  event: 'product_demo_requested',
  eventData: {
    product: 'Enterprise Plan',
    source: 'website'
  }
});
```

## 속도 제한

ActiveCampaign API 속도 제한:

| 요금제 | 속도 제한 | 세부 사항 |
| --- | --- | --- |
| Lite | 5 요청/초 | 계정당 |
| Plus | 10 요청/초 | 계정당 |
| Professional | 10 요청/초 | 계정당 |
| Enterprise | 20 요청/초 | 계정당 |

추가 제한:

- **대량 가져오기**: 배치당 250개 연락처
- **대량 가져오기 빈도**: 한 번에 1개 가져오기
- **이벤트 추적**: 2 요청/초
- **일일 한도**: 명시적 일일 한도 없음 (속도 기반만)

속도 제한 처리

ActiveCampaign은 한도를 초과하면 `429 Too Many Requests`를 반환합니다. `Retry-After` 헤더 값으로 재시도 로직을 구현하십시오.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 403 Forbidden | 잘못된 API 키 또는 URL | AC Settings > Developer에서 API URL 및 키 확인 |
| 연락처가 동기화되지 않음 | 중복 이메일 처리 | upsert 동작을 위해 `/contact/sync` 엔드포인트 사용 |
| 맞춤 필드가 비어 있음 | 필드 ID 불일치 | 레이블이 아닌 ID로 필드 매핑 (레이블은 변경될 수 있음) |
| 웹훅이 수신되지 않음 | 웹훅이 구성되지 않음 | AC Settings > Developer > Webhooks에서 웹훅 설정 |
| 거래가 생성되지 않음 | 필수 필드 누락 | 파이프라인, 단계, 연락처가 제공되었는지 확인 |

### 디버그 모드

자세한 로깅 활성화:

```yaml
connectors:
  activecampaign:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### 연결 테스트

```bash
tajo connectors test activecampaign
# ✓ API 연결 성공
# ✓ 연락처 읽기 가능
# ✓ 거래 읽기 가능
# ✓ 자동화 접근 가능
# ✓ 이벤트 추적 활성화됨
```

## 모범 사례

1. **연락처 동기화 엔드포인트 사용** - 별도의 생성/업데이트 대신 upsert 작업에 `/contact/sync` 사용
2. **ID로 필드 매핑** - 맞춤 필드 ID는 안정적; 레이블은 변경될 수 있음
3. **목록 멤버십 보존** - 연락처 데이터와 함께 목록 할당 마이그레이션
4. **거래 파이프라인 동기화** - 일관된 CRM 보고를 위해 파이프라인 단계 매핑
5. **이벤트 추적 구현** - Brevo의 행동 데이터를 위해 사이트 추적 사용
6. **일괄 가져오기** - 1,000개 이상의 연락처 데이터 세트에 대량 가져오기 사용

## 보안

- **API 키 인증** - `Api-Token` 헤더를 통한 토큰 기반 접근
- **웹훅 확인** - 웹훅 소스 IP 범위 검증
- **TLS 암호화** - HTTPS를 통한 모든 API 통신 암호화
- **계정 수준 접근** - API 키는 전체 계정 접근을 제공; 주의해서 사용
- **IP 제한** - Enterprise 요금제에서 사용 가능

## 관련 리소스

- [ActiveCampaign API 문서](https://developers.activecampaign.com/reference/overview)
- [ActiveCampaign 웹훅 가이드](https://developers.activecampaign.com/page/webhooks)
- [Mailchimp 커넥터](https://tajo.io/kr/docs/connectors/marketing/mailchimp)
- [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)