--- title: "WooCommerce 连接器" description: "完整的 WooCommerce 集成指南，通过 Tajo 将客户、订单、产品和购物车事件与 Brevo 同步。" url: https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce/ markdown: https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce.md lang: zh-CN robots: noindex --- 申请抢先体验 请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。 # WooCommerce 连接器 连接器状态: 开发中 正在构建，尚未验证。 | 来源字段 | 目标字段 | 示例值 | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | 通过 Tajo 将您的 WooCommerce 商店连接到 Brevo，实现完整的电商数据同步。利用 WooCommerce REST API 同步客户、订单、产品和优惠券数据，助力精准营销活动和自动化工作流。 ## 概览 | 属性 | 值 | | --- | --- | | **平台** | WooCommerce（WordPress） | | **类别** | 电子商务 | | **设置复杂度** | 中等 | | **官方集成** | 否 | | **同步数据** | 客户、订单、产品、优惠券 | | **可用技能** | 10 | ## 功能 - **客户同步** - 实时将客户数据同步到 Brevo 联系人 - **订单跟踪** - 完整的订单生命周期事件跟踪，用于购后流程 - **产品目录同步** - 同步产品和变体，用于邮件推荐 - **优惠券管理** - 同步优惠码，用于促销活动 - **Webhook 支持** - 通过 WooCommerce Webhook 实时更新 - **购物车放弃** - 追踪并挽回放弃的购物车 - **多站点支持** - 连接 WordPress 多站点 WooCommerce 安装 - **自定义 Meta 字段** - 将 WooCommerce 自定义 Meta 映射到 Brevo 属性 ## 前提条件 开始之前，请确保您已具备： 1. 已安装并激活 WooCommerce 插件的 WordPress 站点 2. 已启用 WooCommerce REST API（设置 > 高级 > REST API） 3. 已生成 API 消费者密钥和消费者密钥 4. 您的站点必须使用 HTTPS 进行 API 认证 5. 具有 API 访问权限的 Brevo 账户 6. 具有 API 凭据的 Tajo 账户 ## 认证 ### REST API 密钥 WooCommerce 使用消费者密钥对进行认证。在 WooCommerce > 设置 > 高级 > REST API 中生成。 #### OAuth 1.0a（HTTPS 站点） ```bash curl https://yourstore.com/wp-json/wc/v3/orders \ -u "consumer_key:consumer_secret" ``` #### 查询字符串认证（HTTPS） ```bash curl "https://yourstore.com/wp-json/wc/v3/orders?consumer_key=ck_xxx&consumer_secret=cs_xxx" ``` ### 权限级别 | 权限 | 访问级别 | | --- | --- | | **读取** | 仅查看资源 | | **写入** | 创建和编辑资源 | | **读/写** | 完整 CRUD 访问 | ## 配置 ### 基础设置 ```yaml 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 属性： ```yaml 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 ``` ### Webhook 配置 在 WooCommerce > 设置 > 高级 > Webhook 中注册 Webhook： ```yaml 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 连接器 ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); // Connect WooCommerce store await tajo.connectors.connect('woocommerce', { storeUrl: 'https://yourstore.com', consumerKey: process.env.WC_CONSUMER_KEY, consumerSecret: process.env.WC_CONSUMER_SECRET }); ``` ### 获取并同步客户 ```javascript // Fetch customers using WooCommerce REST API const 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 pagination const 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 headers const totalPages = response.headers['x-wp-totalpages']; const totalItems = response.headers['x-wp-total']; ``` ### 处理 Webhook 事件 ```javascript // WooCommerce webhook handler app.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'); }); ``` ### 批量操作 ```javascript // Batch create, update, and delete products const 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） | ## 最佳实践 1. **使用 Webhook 实现实时同步** - 配置 WooCommerce Webhook 而非轮询 API 2. **验证 Webhook 签名** - 始终验证 `X-WC-Webhook-Signature` 头 3. **所有列表请求分页** - 使用 `page` 和 `per_page` 参数；检查 `X-WP-TotalPages` 头 4. **使用 `_fields` 参数** - 仅请求所需字段以减少响应大小并提高性能 5. **批量操作** - 使用批量端点进行大量创建/更新/删除（最多 100 条） 6. **安排大型同步** - 在非高峰时段运行初始全量同步，避免服务器压力 7. **启用 HTTPS** - WooCommerce API 需要 HTTPS 进行 OAuth 认证 ## 安全 - **OAuth 1.0a** - 通过消费者密钥对进行安全认证 - **HMAC Webhook 签名** - 入站 Webhook 的 SHA-256 签名验证 - **需要 HTTPS** - API 需要 TLS 加密进行认证 - **权限范围** - API 密钥可设置为读取、写入或读/写 - **WordPress 安全** - 受益于 WordPress 核心安全更新 - **PCI 考量** - 支付数据由 WooCommerce 支付网关处理，不通过 API 暴露 ## 相关资源 - [Shopify 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify) - [BigCommerce 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/bigcommerce) - [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync) - [弃购恢复技能](https://tajo.io/zh-cn/docs/skills/email-marketing/abandoned-cart)