WooCommerce 连接器
WooCommerce 连接器
通过 Tajo 将您的 WooCommerce 商店连接到 Brevo,实现完整的电商数据同步。利用 WooCommerce REST API 同步客户、订单、产品和优惠券数据,助力精准营销活动和自动化工作流。
概览
| 属性 | 值 |
|---|---|
| 平台 | WooCommerce(WordPress) |
| 类别 | 电子商务 |
| 设置复杂度 | 中等 |
| 官方集成 | 否 |
| 同步数据 | 客户、订单、产品、优惠券 |
| 可用技能 | 10 |
功能
- 客户同步 - 实时将客户数据同步到 Brevo 联系人
- 订单跟踪 - 完整的订单生命周期事件跟踪,用于购后流程
- 产品目录同步 - 同步产品和变体,用于邮件推荐
- 优惠券管理 - 同步优惠码,用于促销活动
- Webhook 支持 - 通过 WooCommerce Webhook 实时更新
- 购物车放弃 - 追踪并挽回放弃的购物车
- 多站点支持 - 连接 WordPress 多站点 WooCommerce 安装
- 自定义 Meta 字段 - 将 WooCommerce 自定义 Meta 映射到 Brevo 属性
前提条件
开始之前,请确保您已具备:
- 已安装并激活 WooCommerce 插件的 WordPress 站点
- 已启用 WooCommerce REST API(设置 > 高级 > REST API)
- 已生成 API 消费者密钥和消费者密钥
- 您的站点必须使用 HTTPS 进行 API 认证
- 具有 API 访问权限的 Brevo 账户
- 具有 API 凭据的 Tajo 账户
认证
REST API 密钥
WooCommerce 使用消费者密钥对进行认证。在 WooCommerce > 设置 > 高级 > 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"权限级别
| 权限 | 访问级别 |
|---|---|
| 读取 | 仅查看资源 |
| 写入 | 创建和编辑资源 |
| 读/写 | 完整 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_CATEGORYWebhook 配置
在 WooCommerce > 设置 > 高级 > Webhook 中注册 Webhook:
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 端点
| 方法 | 端点 | 描述 |
|---|---|---|
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 | 列出产品变体 |
GET | /wc/v3/coupons | 列出优惠券 |
GET | /wc/v3/reports/sales | 获取销售报告 |
GET | /wc/v3/reports/top_sellers | 获取热销商品 |
POST | /wc/v3/webhooks | 创建 Webhook |
代码示例
初始化 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'];处理 Webhook 事件
// 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 设置中重新生成消费者密钥 |
403 Forbidden | 权限不足 | 将 API 密钥设置为读/写访问 |
| SSL 证书错误 | 站点 SSL 无效 | 确保有效的 SSL 证书;仅在测试时设置 verify_ssl: false |
| Webhook 未触发 | WordPress Cron 禁用 | 启用 WP-Cron 或配置服务器级 Cron |
| API 响应缓慢 | 数据库过大 | 优化 WordPress 数据库,使用 _fields 参数 |
| 自定义字段缺失 | Meta 数据未暴露 | 使用 meta_data 字段访问自定义 Meta |
| 分页问题 | 默认页面大小 | 明确设置 per_page 参数(最大 100) |
最佳实践
- 使用 Webhook 实现实时同步 - 配置 WooCommerce Webhook 而非轮询 API
- 验证 Webhook 签名 - 始终验证
X-WC-Webhook-Signature头 - 所有列表请求分页 - 使用
page和per_page参数;检查X-WP-TotalPages头 - 使用
_fields参数 - 仅请求所需字段以减少响应大小并提高性能 - 批量操作 - 使用批量端点进行大量创建/更新/删除(最多 100 条)
- 安排大型同步 - 在非高峰时段运行初始全量同步,避免服务器压力
- 启用 HTTPS - WooCommerce API 需要 HTTPS 进行 OAuth 认证
安全
- OAuth 1.0a - 通过消费者密钥对进行安全认证
- HMAC Webhook 签名 - 入站 Webhook 的 SHA-256 签名验证
- 需要 HTTPS - API 需要 TLS 加密进行认证
- 权限范围 - API 密钥可设置为读取、写入或读/写
- WordPress 安全 - 受益于 WordPress 核心安全更新
- PCI 考量 - 支付数据由 WooCommerce 支付网关处理,不通过 API 暴露