--- title: "Klaviyo 커넥터" description: "Tajo를 통해 Klaviyo의 프로필, 이벤트, 목록, 세그먼트, 캠페인 데이터를 Brevo와 동기화하는 완전한 통합 가이드입니다." url: https://tajo.io/kr/docs/connectors/marketing/klaviyo/ markdown: https://tajo.io/kr/docs/connectors/marketing/klaviyo.md lang: ko-KR robots: noindex --- Tajo 사전 이용 신청 이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다. # Klaviyo 커넥터 커넥터 상태: 개발 중 구축 중입니다. 아직 검증되지 않았습니다. | 원본 필드 | 대상 필드 | 예시 값 | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Tajo를 통해 Klaviyo를 Brevo에 연결하여 플랫폼 간 마케팅 데이터를 마이그레이션하거나 동기화하십시오. 프로필, 이벤트, 목록, 세그먼트, 플로, 캠페인 데이터를 동기화하여 통합된 다중 채널 마케팅 전략을 수립하십시오. ## 개요 | 속성 | 값 | | --- | --- | | **플랫폼** | Klaviyo | | **카테고리** | Marketing | | **설정 복잡도** | 중간 | | **공식 통합** | 아니오 | | **동기화 데이터** | 프로필, 이벤트, 목록, 세그먼트, 캠페인 | | **사용 가능한 스킬** | 10 | | **API 표준** | JSON:API | ## 기능 - **프로필 동기화** - Klaviyo와 Brevo 간 고객 프로필의 양방향 동기화 - **이벤트 전달** - 자동화 트리거를 위해 Klaviyo에서 추적한 이벤트를 Brevo로 전달 - **목록 마이그레이션** - Klaviyo 목록을 Brevo 연락처 목록으로 동기화 - **세그먼트 동기화** - Klaviyo 세그먼트를 Brevo 목록 또는 세그먼트로 내보내기 - **플로 데이터 내보내기** - 크로스 플랫폼 분석을 위해 플로 성능 데이터 가져오기 - **캠페인 동기화** - Klaviyo 및 Brevo 채널 간 캠페인 조정 - **카탈로그 동기화** - 플랫폼 간 제품 카탈로그 미러링 - **쿠폰 관리** - 쿠폰 코드 및 사용 데이터 동기화 ## 사전 요구 사항 시작하기 전에 다음이 준비되어 있는지 확인하십시오. 1. API 접근이 가능한 Klaviyo 계정 2. 적절한 범위가 있는 Private API Key 3. Klaviyo Public API Key (6자 회사 ID) 4. API 접근이 가능한 Brevo 계정 5. API 자격 증명이 있는 Tajo 계정 ## 인증 ### Private API Key Klaviyo는 서버 측 인증을 위해 범위 지정된 접근 권한이 있는 비공개 API 키를 사용합니다. `Authorization` 헤더에 키를 설정하십시오. ```bash curl https://a.klaviyo.com/api/profiles/ \ -H "Authorization: Klaviyo-API-Key your-private-api-key" \ -H "revision: 2026-01-15" ``` ### API 키 범위 비공개 키를 생성할 때 범위를 구성하십시오. | 범위 | 접근 | 설명 | | --- | --- | --- | | `profiles` | Read/Full | 연락처 프로필 접근 | | `events` | Read/Full | 추적된 이벤트 접근 | | `lists` | Read/Full | 연락처 목록 접근 | | `segments` | Read | 세그먼트 접근 | | `campaigns` | Read | 캠페인 데이터 접근 | | `metrics` | Read | 지표 정의 접근 | | `flows` | Read | 플로 구성 접근 | | `catalogs` | Read | 제품 카탈로그 접근 | ### Public API Key 클라이언트 측 추적에는 6자 회사 ID를 사용하십시오. ```bash curl -X POST "https://a.klaviyo.com/client/events/?company_id=COMPANY_ID" \ -H "Content-Type: application/json" \ -d '{"data": {...}}' ``` ### OAuth (파트너 통합) Klaviyo는 향상된 보안 및 속도 제한을 제공하는 기술 파트너용 OAuth를 지원합니다. ```bash curl https://a.klaviyo.com/api/profiles/ \ -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \ -H "revision: 2026-01-15" ``` ## 구성 ### 기본 설정 ```yaml connectors: klaviyo: enabled: true private_api_key: "your-klaviyo-private-key" public_api_key: "XXXXXX" api_revision: "2026-01-15" # 데이터 동기화 옵션 sync: profiles: true events: true lists: true segments: true catalogs: false # Brevo 목록 할당 lists: all_contacts: 20 subscribers: 21 high_value: 22 ``` ### 프로필 매핑 Klaviyo 프로필 속성을 Brevo 연락처 속성에 매핑합니다. ```yaml profile_mapping: email: email first_name: FIRSTNAME last_name: LASTNAME phone_number: SMS city: CITY region: REGION country: COUNTRY zip: ZIP organization: COMPANY title: JOB_TITLE # 맞춤 속성 lifetime_value: LTV total_orders: ORDER_COUNT last_order_date: LAST_ORDER_DATE preferred_channel: CHANNEL_PREF ``` ### 이벤트 매핑 Klaviyo 지표를 Brevo 이벤트에 매핑합니다. ```yaml event_mapping: "Placed Order": "order_completed" "Ordered Product": "product_purchased" "Started Checkout": "checkout_started" "Added to Cart": "cart_updated" "Viewed Product": "product_viewed" "Subscribed to List": "customer_subscribed" "Received Email": "email_received" "Opened Email": "email_opened" "Clicked Email": "email_clicked" ``` ## API 엔드포인트 | 메서드 | 엔드포인트 | 설명 | | --- | --- | --- | | `GET` | `/api/profiles/` | 프로필 목록 | | `POST` | `/api/profiles/` | 프로필 생성 | | `PATCH` | `/api/profiles/{id}/` | 프로필 업데이트 | | `POST` | `/api/profile-merge/` | 중복 프로필 병합 | | `GET` | `/api/events/` | 이벤트 목록 | | `POST` | `/api/events/` | 이벤트 생성 | | `GET` | `/api/lists/` | 모든 목록 | | `POST` | `/api/lists/{id}/relationships/profiles/` | 목록에 프로필 추가 | | `GET` | `/api/segments/` | 세그먼트 목록 | | `GET` | `/api/campaigns/` | 캠페인 목록 | | `GET` | `/api/flows/` | 플로 목록 | | `GET` | `/api/metrics/` | 지표 목록 | | `POST` | `/api/metric-aggregates/` | 지표 집계 쿼리 | | `GET` | `/api/catalog-items/` | 카탈로그 항목 목록 | ## 코드 예제 ### Klaviyo 커넥터 초기화 ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); // Klaviyo 계정 연결 await tajo.connectors.connect('klaviyo', { privateApiKey: process.env.KLAVIYO_PRIVATE_KEY, publicApiKey: process.env.KLAVIYO_PUBLIC_KEY }); ``` ### 프로필을 Brevo로 동기화 ```javascript // Klaviyo 프로필을 가져와서 Brevo로 동기화 const response = await fetch('https://a.klaviyo.com/api/profiles/', { headers: { 'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`, 'revision': '2026-01-15', 'Accept': 'application/vnd.api+json' } }); const { data } = await response.json(); // 각 프로필은 JSON:API 형식을 따름 // { // "type": "profile", // "id": "01ABCDEF", // "attributes": { // "email": "jane@example.com", // "first_name": "Jane", // "last_name": "Kim", // "phone_number": "+15551234567", // "properties": { "lifetime_value": 450.00 } // } // } ``` ### 이벤트 생성 ```javascript // Klaviyo에서 이벤트 추적 (Tajo를 통해 Brevo로 전달됨) await fetch('https://a.klaviyo.com/api/events/', { method: 'POST', headers: { 'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`, 'revision': '2026-01-15', 'Content-Type': 'application/vnd.api+json', 'Accept': 'application/vnd.api+json' }, body: JSON.stringify({ data: { type: 'event', attributes: { metric: { data: { type: 'metric', attributes: { name: 'Placed Order' } } }, profile: { data: { type: 'profile', attributes: { email: 'jane@example.com' } } }, properties: { OrderId: 'ORD-1234', Value: 89.99, Items: [ { ProductName: 'Widget Pro', Price: 89.99, Quantity: 1 } ] }, value: 89.99 } } }) }); ``` ### 지표 집계 쿼리 ```javascript // 보고를 위한 집계 지표 데이터 가져오기 await fetch('https://a.klaviyo.com/api/metric-aggregates/', { method: 'POST', headers: { 'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`, 'revision': '2026-01-15', 'Content-Type': 'application/vnd.api+json' }, body: JSON.stringify({ data: { type: 'metric-aggregate', attributes: { metric_id: 'METRIC_ID', measurements: ['count', 'sum_value'], interval: 'day', filter: ['greater-or-equal(datetime,2024-01-01)', 'less-than(datetime,2024-02-01)'] } } }) }); ``` ## 속도 제한 | 인증 | 버스트 제한 | 정상 제한 | | --- | --- | --- | | **Private API Key** | 75 요청/초 | 700 요청/분 | | **OAuth** | 150 요청/초 | 1,500 요청/분 | | **Client API** | 100 요청/초 | N/A | | **Bulk 작업** | 10 요청/초 | 100 요청/분 | API Revision 필수 모든 Klaviyo API 요청은 유효한 API 버전 날짜로 설정된 `revision` 헤더가 필요합니다 (예: `2026-01-15`). 이 헤더가 없는 요청은 거부됩니다. ## 문제 해결 | 문제 | 원인 | 해결 방법 | | --- | --- | --- | | `400 Bad Request` | 잘못되거나 누락된 API 키 | 비공개 API 키가 올바른지 확인 | | `403 Forbidden` | 범위 부족 | API 키 범위가 필수 권한과 일치하는지 확인 | | `revision` 헤더 누락 | 헤더가 설정되지 않음 | 모든 요청에 `revision: 2026-01-15` 추가 | | 프로필을 찾을 수 없음 | 잘못된 식별자 | 조회에 이메일이 아닌 Klaviyo 프로필 ID 사용 | | 이벤트가 동기화되지 않음 | 잘못된 지표 이름 | Klaviyo에 정의된 정확한 지표 이름과 일치 | | `429 Too Many Requests` | 속도 제한 초과 | 지수 백오프 구현, 더 높은 제한을 위해 OAuth 고려 | | JSON:API 형식 오류 | 잘못된 content type | Content-Type 및 Accept 헤더에 `application/vnd.api+json` 사용 | ## 모범 사례 1. **JSON:API 형식 사용** - 모든 요청 및 응답 페이로드에 JSON:API 사양 준수 2. **revision 헤더 설정** - 항상 최신 API 버전 날짜로 `revision` 헤더 포함 3. **Sparse 필드셋 사용** - 페이로드 크기를 줄이기 위해 `?fields[profile]=email,first_name`으로 필요한 필드만 요청 4. **관계 활용** - JSON:API `include` 매개변수를 사용하여 단일 요청으로 관련 리소스 가져오기 5. **커서 페이지네이션 사용** - `page[cursor]` 매개변수로 대량 결과 세트 탐색 6. **Bulk 작업 구현** - 배치 프로필 가져오기 및 이벤트 생성에 Bulk 엔드포인트 사용 7. **더 높은 제한을 위해 OAuth 사용** - OAuth 인증은 비공개 키보다 2배 높은 속도 제한 제공 ## 보안 - **Private API 키 범위** - 리소스 유형별 세분화된 Read/Full 접근 제어 - **OAuth 지원** - 파트너 통합을 위한 보안 토큰 기반 인증 - **Public 키 격리** - 클라이언트 측 키는 생성 전용 작업으로 제한됨 - **TLS 1.2+** - 전송 중 암호화된 모든 API 통신 - **SOC 2 Type II** - Klaviyo는 SOC 2 Type II 인증을 받음 - **GDPR 준수** - 프로필 삭제 요청을 위한 Data Privacy API ## 관련 리소스 - [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo) - [Google Ads 커넥터](https://tajo.io/kr/docs/connectors/marketing/google-ads) - [Meta Ads 커넥터](https://tajo.io/kr/docs/connectors/marketing/meta-ads) - [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)