WooCommerce 커넥터
WooCommerce 스토어를 Tajo를 통해 Brevo에 연결하여 완전한 이커머스 데이터 동기화를 구현하세요. WooCommerce REST API를 활용해 고객, 주문, 제품, 쿠폰 데이터를 동기화하면 타겟팅된 마케팅 캠페인과 자동화된 워크플로우를 구성할 수 있습니다.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | WooCommerce (WordPress) |
| 카테고리 | 이커머스 |
| 설정 난이도 | 보통 |
| 공식 통합 | 아니오 |
| 동기화되는 데이터 | 고객, 주문, 제품, 쿠폰 |
| 사용 가능한 스킬 | 10 |
주요 기능
- 고객 동기화 - Brevo 연락처로의 실시간 고객 데이터 동기화
- 주문 추적 - 구매 후 플로우를 위한 전체 주문 라이프사이클 이벤트 추적
- 제품 카탈로그 동기화 - 이메일 추천을 위한 제품 및 variation 동기화
- 쿠폰 관리 - 프로모션 캠페인을 위한 쿠폰 코드 동기화
- 웹훅 지원 - WooCommerce 웹훅을 통한 실시간 업데이트
- 장바구니 이탈 - 이탈한 장바구니 추적 및 복구
- 다중 사이트 지원 - WordPress 멀티사이트 WooCommerce 설치 지원
- 커스텀 메타 필드 - WooCommerce 커스텀 메타를 Brevo 속성에 매핑
사전 준비 사항
시작하기 전에 다음 사항이 준비되어 있어야 합니다.
- WooCommerce 플러그인이 설치 및 활성화된 WordPress 사이트
- WooCommerce REST API 활성화 (Settings > Advanced > REST API)
- 생성된 API Consumer Key 및 Consumer Secret
- API 인증을 위해 사이트가 HTTPS를 사용해야 합니다
- API 액세스가 가능한 Brevo 계정
- API 자격 증명이 있는 Tajo 계정
인증
REST API 키
WooCommerce는 인증에 Consumer Key와 Consumer Secret 쌍을 사용합니다. WooCommerce > Settings > Advanced > REST API에서 이를 생성할 수 있습니다.
OAuth 1.0a (HTTPS 사이트)
curl https://yourstore.com/wp-json/wc/v3/orders \ -u "consumer_key:consumer_secret"쿼리 문자열 인증 (HTTPS)
curl "https://yourstore.com/wp-json/wc/v3/orders?consumer_key=ck_xxx&consumer_secret=cs_xxx"권한 수준
| 권한 | 액세스 |
|---|---|
| Read | 리소스 조회만 가능 |
| Write | 리소스 생성 및 편집 |
| Read/Write | 전체 CRUD 액세스 |
설정
기본 설정
connectors: woocommerce: enabled: true store_url: "https://yourstore.com" consumer_key: "ck_your_consumer_key" consumer_secret: "cs_your_consumer_secret" api_version: "wc/v3" verify_ssl: true
# Data sync options sync: customers: true orders: true products: true coupons: true
# Brevo list assignment lists: all_customers: 50 buyers: 51 abandoned_cart: 52고객 필드 매핑
WooCommerce 고객 필드를 Brevo 속성에 매핑합니다.
customer_mapping: email: email first_name: FIRSTNAME last_name: LASTNAME billing.phone: SMS billing.company: COMPANY billing.city: CITY billing.state: STATE billing.country: COUNTRY billing.postcode: ZIP
# E-commerce metrics (computed) orders_count: ORDER_COUNT total_spent: TOTAL_SPENT date_created: SIGNUP_DATE
# Meta fields meta_data.loyalty_points: LOYALTY_POINTS meta_data.preferred_category: PREF_CATEGORY웹훅 설정
WooCommerce > Settings > Advanced > Webhooks에서 웹훅을 등록합니다.
webhooks: - topic: "customer.created" event: "customer_created" - topic: "customer.updated" event: "customer_updated" - topic: "order.created" event: "order_placed" - topic: "order.updated" event: "order_updated" - topic: "order.completed" event: "order_fulfilled" - topic: "order.refunded" event: "order_refunded" - topic: "coupon.created" event: "coupon_created" - topic: "product.created" event: "product_added" - topic: "product.updated" event: "product_updated"API 엔드포인트
| Method | 엔드포인트 | 설명 |
|---|---|---|
GET | /wc/v3/customers | 고객 목록 조회 |
POST | /wc/v3/customers | 고객 생성 |
GET | /wc/v3/customers/{id} | 고객 조회 |
PUT | /wc/v3/customers/{id} | 고객 업데이트 |
GET | /wc/v3/orders | 주문 목록 조회 |
POST | /wc/v3/orders | 주문 생성 |
GET | /wc/v3/orders/{id} | 주문 조회 |
GET | /wc/v3/products | 제품 목록 조회 |
GET | /wc/v3/products/{id} | 제품 조회 |
GET | /wc/v3/products/{id}/variations | 제품 variation 목록 |
GET | /wc/v3/coupons | 쿠폰 목록 조회 |
GET | /wc/v3/reports/sales | 판매 리포트 조회 |
GET | /wc/v3/reports/top_sellers | 베스트셀러 조회 |
POST | /wc/v3/webhooks | 웹훅 생성 |
코드 예제
WooCommerce 커넥터 초기화
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect WooCommerce storeawait tajo.connectors.connect('woocommerce', { storeUrl: 'https://yourstore.com', consumerKey: process.env.WC_CONSUMER_KEY, consumerSecret: process.env.WC_CONSUMER_SECRET});고객 가져오기 및 동기화
// Fetch customers using WooCommerce REST APIconst WooCommerce = require('@woocommerce/woocommerce-rest-api').default;
const api = new WooCommerce({ url: 'https://yourstore.com', consumerKey: process.env.WC_CONSUMER_KEY, consumerSecret: process.env.WC_CONSUMER_SECRET, version: 'wc/v3'});
// List customers with paginationconst response = await api.get('customers', { per_page: 100, page: 1, orderby: 'registered_date', order: 'desc'});
const customers = response.data;// [{ id, email, first_name, last_name, billing, shipping, ... }]
// Pagination info from headersconst totalPages = response.headers['x-wp-totalpages'];const totalItems = response.headers['x-wp-total'];웹훅 이벤트 처리
// WooCommerce webhook handlerapp.post('/webhooks/woocommerce', async (req, res) => { const topic = req.headers['x-wc-webhook-topic']; const signature = req.headers['x-wc-webhook-signature'];
// Verify webhook signature const expectedSignature = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(JSON.stringify(req.body)) .digest('base64');
if (signature !== expectedSignature) { return res.status(401).send('Invalid signature'); }
// Forward to Tajo await tajo.connectors.handleWebhook('woocommerce', { topic, payload: req.body });
res.status(200).send('OK');});배치 작업
// Batch create, update, and delete productsconst batchResponse = await api.post('products/batch', { create: [ { name: 'New Product', type: 'simple', regular_price: '19.99' } ], update: [ { id: 123, regular_price: '24.99' } ], delete: [456]});요청 제한
WooCommerce 자체는 API 요청 제한을 두지 않지만, 기반이 되는 WordPress 서버와 호스팅 제공업체가 제한을 부과할 수 있습니다.
| 요인 | 일반적인 제한 | 세부 사항 |
|---|---|---|
| 공유 호스팅 | 50-100회/분 | 호스트에 따라 다름 |
| 관리형 WP 호스팅 | 200-500회/분 | WP Engine, Kinsta 등 |
| 자체 호스팅 | 엄격한 제한 없음 | 서버 리소스에 의해 제한 |
| 페이지당 | 최대 100개 레코드 | 기본값은 10 |
| 배치 작업 | 배치당 100개 항목 | 생성, 업데이트 또는 삭제 |
서버 성능
대규모 WooCommerce 스토어는 느린 API 응답을 경험할 수 있습니다. 페이지네이션을 사용하고, _fields 파라미터로 필드를 제한하며, 대량 동기화는 비혼잡 시간에 예약하세요.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | 유효하지 않은 API 키 | WooCommerce 설정에서 Consumer Key/Secret을 재생성하세요 |
403 Forbidden | 불충분한 권한 | API 키를 Read/Write 액세스로 설정하세요 |
| SSL 인증서 오류 | 사이트에 유효하지 않은 SSL | 유효한 SSL 인증서를 확인하세요. 테스트용으로만 verify_ssl: false 설정 |
| 웹훅이 실행되지 않음 | WordPress cron 비활성화 | WP-Cron을 활성화하거나 서버 수준 cron을 구성하세요 |
| 느린 API 응답 | 대규모 데이터베이스 | WordPress 데이터베이스를 최적화하고 _fields 파라미터를 사용하세요 |
| 커스텀 필드 누락 | 메타 데이터가 노출되지 않음 | 커스텀 메타에 접근하려면 meta_data 필드를 사용하세요 |
| 페이지네이션 문제 | 기본 페이지 크기 | per_page 파라미터를 명시적으로 설정하세요 (최대 100) |
모범 사례
- 실시간 동기화에 웹훅 사용 - API 폴링 대신 WooCommerce 웹훅을 구성하세요
- 웹훅 서명 검증 - 항상
X-WC-Webhook-Signature헤더를 검증하세요 - 모든 목록 요청 페이지네이션 -
page및per_page파라미터를 사용하고X-WP-TotalPages헤더를 확인하세요 _fields파라미터 사용 - 필요한 필드만 요청하여 응답 크기를 줄이고 성능을 향상하세요- 배치 작업 - 대량 생성/업데이트/삭제 작업에 배치 엔드포인트를 사용하세요 (최대 100개 항목)
- 대규모 동기화 예약 - 서버 부담을 피하기 위해 초기 전체 동기화는 비혼잡 시간에 실행하세요
- HTTPS 활성화 - WooCommerce API는 OAuth 인증을 위해 HTTPS가 필요합니다
보안
- OAuth 1.0a - Consumer Key/Secret 쌍을 통한 안전한 인증
- HMAC 웹훅 서명 - 수신 웹훅에 대한 SHA-256 서명 검증
- HTTPS 필수 - API는 인증을 위해 TLS 암호화가 필요합니다
- 권한 스코핑 - API 키를 Read, Write 또는 Read/Write로 설정할 수 있습니다
- WordPress 보안 - WordPress 코어 보안 업데이트의 혜택을 받습니다
- PCI 고려사항 - 결제 데이터는 WooCommerce 결제 게이트웨이가 처리하며 API를 통해 노출되지 않습니다