WooCommerce 커넥터
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를 통해 노출되지 않습니다