ToolJet 连接 WooCommerce 数据源全攻略：从 REST 凭据配置到增删改查实战

本指南面向需要在 ToolJet 中读写 WooCommerce 电商数据的开发者，系统讲解 WooCommerce 数据源的连接配置、凭据获取、查询面板操作方式，以及 Customer / Product / Order / Coupon 四大资源支持的 20 种操作与参数细节。文中同时结合本仓库 WooCommerce 插件实现 的源码，说明连接建立与请求执行的底层原理，帮助你在自己的 ToolJet 工作区里快速搭建订单管理、商品同步、客户查询等内部工具与看板。

数据源概览与能力边界

ToolJet 可以通过 WooCommerce 官方 REST API 连接你的在线商店，实现数据的读取与写入。该数据源封装在仓库的 woocommerce 插件包 中，以 woocommerce-rest-ts-api 作为底层客户端，并固定使用 WooCommerce 的 wc/v3 REST API 版本（见 index.ts）。

从插件的能力划分看，它目前覆盖四类核心电商资源：

资源（Resource）	说明	覆盖的操作
Customer	店铺客户	列表、创建、读取、更新、删除、批量更新
Product	商品	列表、创建、读取、更新、删除、批量更新
Order	订单	列表、创建、读取、更新、删除、批量更新
Coupon	优惠券	列表、创建

也就是说，像"拉取最近订单状态""根据客户邮箱批量更新资料""创建新商品""为订单应用优惠券"这类内部运营需求，都可以直接在 ToolJet 中用可视化查询完成，无需另写后端胶水代码。

前置准备：在 WooCommerce 后台生成 REST API 凭据

建立连接前，你需要先在 WooCommerce 商店后台生成 API 凭据。凭据的官方入口位于商店后台（WooCommerce → Settings → Advanced → REST API 区域）的 REST API 管理页，新增一个应用即可得到下面三样信息（原文档提示对应官方 WooCommerce REST API 认证文档，这里按仓库插件实际使用字段说明）：

• Consumer key（消费者密钥）
• Consumer secret（消费者密钥密文）
• Host（店铺地址）：即商店的站点根 URL，例如 https://your-store.example.com

生成密钥时建议按用途选择读写权限范围：如果查询工具只做数据展示，可授予只读（Read）权限；如果需要新建订单、更新商品等写入能力，则需授予读写（Read/Write）权限。密钥生成后通常只展示一次，请妥善保存，因为 ToolJet 侧会以加密形式存储（详见下文源码分析）。

在 ToolJet 中建立 WooCommerce 连接

添加数据源有两种入口，效果相同：

1. 在查询面板（Query Panel）中点击 + Add new Data source 按钮；
2. 或从 ToolJet 仪表盘进入 Data Sources 页面，点击 + 新增并选择 WooCommerce。

随后在认证表单中填写连接 WooCommerce 所需的三个字段：

字段	表单控件	是否必填	说明
Host	文本输入框	是	你的 WooCommerce 商店根地址
Consumer key	密码框	是	REST API 凭据中的 Consumer key
Consumer secret	密码框	是	REST API 凭据中的 Consumer secret

这三个字段的必填性与输入类型定义在插件 manifest.json 中，其中 consumer_key 与 consumer_secret 被标记为 "encrypted": true（manifest.json），意味着保存后凭据会加密落库，界面上的类型也是 password，不会被明文泄露。

填写完成后保存数据源即可，ToolJet 会调用插件的连接测试逻辑校验凭据是否有效（见下文）。

源码视角：连接与认证测试是如何实现的

连接流程在 index.ts 中非常直观：

async getConnection(sourceOptions: any, _options?: object): Promise<any> {
  const { host, consumer_key, consumer_secret } = sourceOptions;
  const WooCommerce = new WooCommerceRestApi({
    url: host,                    // 商店根地址
    consumerKey: consumer_key,    // Consumer key
    consumerSecret: consumer_secret, // Consumer secret
    version: 'wc/v3',             // WooCommerce WP REST API 版本
  });
  return WooCommerce;
}

三个关键点值得注意：

• 插件把工具界面上输入的 host、consumer_key、consumer_secret 直接映射到 REST 客户端的 url、consumerKey、consumerSecret；
• API 版本被硬编码为 wc/v3，因此目标商店需要启用 WooCommerce 并支持 v3 REST API；
• 保存数据源时执行的测试请求指向 system_status 接口（index.ts），一旦请求失败即抛出 Invalid credentials，提示你检查 Host 与密钥是否填写正确。

在查询面板中执行 WooCommerce 查询

完成连接后即可创建查询，标准操作流程如下：

1. 点击编辑器底部查询管理器中的 + Add 按钮；
2. 在数据源下拉框中选择上一步添加的 WooCommerce；
3. 从 Resource（资源） 下拉框中选择目标资源，再从 Operation（操作） 下拉框选择要执行的操作；
4. 根据需要填写该操作暴露的参数（正文下方给出各资源参数清单）；
5. 点击 Preview 预览输出，或点击 Run 真正触发查询。

:::tip 查询结果可以进一步做数据转换。若想了解如何在表格、下拉框等组件中消费与重塑返回值，请阅读 Transformations 数据转换文档。 :::

插件在收到查询请求后会先解析 resource 与 operation，再路由到对应的处理函数（index.ts）：

switch (resource) {
  case 'customer': result = await customerOpeations(WooCommerce, queryOptions, operation); break;
  case 'product':  result = await productOperations(WooCommerce, queryOptions, operation); break;
  case 'order':    result = await orderOperations(WooCommerce, queryOptions, operation); break;
  case 'coupon':   result = await couponOperations(WooCommerce, queryOptions, operation); break;
}
return { status: 'ok', data: result };

所有成功的查询都会以 { status: 'ok', data: result } 的结构返回，result 中通常包含 HTTP statusCode 与接口返回的数据体，可在后续组件事件中通过 queries.<查询名>.data 引用。插件 manifest 同时声明了查询暴露的变量 isLoading、data、rawData（manifest.json），可供前端绑定加载态与原始数据。

支持的资源与操作一览

Customer（客户）

操作	底层实现	说明
list customer	GET customers	分页/条件列出客户，支持搜索、邮箱、角色等过滤
create customer	POST customers	在 Data（body）中传入客户信息 JSON 创建客户
retrieve customer	GET customers/{id}	按 Customer ID 读取单个客户
update customer	PUT customers/{id}	按 Customer ID 更新，变更内容放在 Data 中
delete customer	DELETE customers/{id}	按 Customer ID 删除，强制删除（force: true）
batch update customer	POST customers/batch	批量创建/更新/删除，详见下文"批量操作"

Product（商品）

操作	底层实现	说明
list product	GET products	商品列表，支持按 SKU、类型、状态、分类、价格区间、库存等过滤
create product	POST products	在 Data 中传入商品 JSON 创建商品
retrieve product	GET products/{id}	按 Product ID 读取单个商品
update product	PUT products/{id}	按 Product ID 更新商品属性
delete product	DELETE products/{id}	按 Product ID 删除商品（强制删除）
batch update product	POST products/batch	批量创建/更新/删除商品

Order（订单）

操作	底层实现	说明
list order	GET orders	订单列表，支持按状态、客户、商品、日期区间过滤
create order	POST orders	在 Data 中传入订单 JSON（含商品明细）创建订单
retrieve order	GET orders/{id}	按 Order ID 读取单个订单
update order	PUT orders/{id}	按 Order ID 更新订单（例如修改状态、备注）
delete order	DELETE orders/{id}	按 Order ID 删除订单（强制删除）
batch update order	POST orders/batch	批量创建/更新/删除订单

Coupon（优惠券）

操作	底层实现	说明
list coupon	GET coupons	优惠券列表，支持按优惠码 code 过滤
create coupon	POST coupons	在 Data 中传入优惠券 JSON 创建优惠券

需要说明的是：原文档指出更多操作细节与完整参数语义可参考 WooCommerce 官方 REST API 文档；从当前插件实现看，Coupon 资源目前仅开放了列表与创建两个操作（operation.ts）。

常用参数详解

各操作的参数因资源而异。除 Data 与各类 ID 外，绝大部分参数是可选的过滤/分页条件，只有填入才会被拼接进请求 URL（源码用展开运算符做条件组装，见 operation.ts）。参数在界面上的声明集中在 definitions.ts。

通用列表参数（四类资源列表操作均支持）

参数	说明
Context	响应数据的上下文（如 view），影响返回字段范围
Page	当前页码，从 1 开始
Per Page	每页条数，默认与上限以 WooCommerce 侧配置为准
Search	模糊搜索关键词
Exclude	需要排除的 ID 列表，多个用逗号分隔
Include	仅返回的 ID 列表
Offset	偏移量，跳过前 N 条记录
Order	排序方向（如 asc / desc）
Order By	排序字段（如 date、id、title）

Customer 专属参数

参数	说明
Email	按邮箱精确过滤客户
Role	按角色过滤（如 customer）
Customer ID	读取/更新/删除单个客户时必填的资源 ID
Data	创建/更新/批量操作时填写的请求体 JSON

Product 专属参数

参数	说明
Slug / SKU	按别名或 SKU 过滤
Status	商品状态（如 publish、draft、private）
Type	商品类型（如 simple、variable、grouped）
Featured	是否仅筛选精选商品
Category / Tag	按分类 ID 或标签 ID 过滤
Shipping Class / Tax Class	按配送类或税类过滤
Attribute / Attribute Term	按商品属性及属性项过滤
On Sale	是否仅筛选促销商品
Min Price / Max Price	价格区间过滤
Stock Status	库存状态（如 instock、outofstock）
Before / After	按修改时间上/下限过滤（ISO8601 格式）
Parent / Parent Exclude	按父商品 ID 过滤/排除变体商品
Product ID	读取/更新/删除单个商品时必填

Order 专属参数

参数	说明
Status	订单状态（如 pending、processing、completed、cancelled）
Customer	按客户 ID 过滤该客户的全部订单
Product	按商品 ID 过滤包含该商品的订单
Decimal Point	金额精度（影响返回金额小数位）
Before / After	按创建时间区间过滤
Order ID	读取/更新/删除单个订单时必填

Coupon 专属参数

参数	说明
Code	按优惠码过滤优惠券
Data	创建优惠券时的请求体 JSON

Data（请求体）与 JSON5

Data 字段是创建/更新/批量操作的核心参数，类型为代码编辑器（codehinter，高度 150px，见 definitions.ts）。插件内部用 JSON5 解析该字段（operation.ts），因此除了标准 JSON，还允许尾随逗号等更宽松的书写习惯。请求体会被原样透传给 WooCommerce REST API，因此其结构需遵循对应资源的官方 API Schema。例如创建客户的 Data 可写为：

{
  "email": "[e-mail]",
  "first_name": "Jane",
  "last_name": "Doe",
  "billing": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[e-mail]"
  }
}

创建订单时通常需要包含 payment_method、billing、shipping 与 line_items（商品行项数组）等字段；更新操作只需携带要变更的字段。

进阶用法：批量操作与结果处理

批量操作（Batch Update）

Customer / Product / Order 三类资源都支持 batch update。它对应 REST API 的 <resource>/batch 端点（operation.ts），Data 中按 create、update、delete 三个键组织批量指令：

{
  "create": [{ "name": "示例商品 A", "type": "simple", "regular_price": "10.00" }],
  "update": [{ "id": 123, "regular_price": "12.00" }],
  "delete": [{ "id": 456 }]
}

适合在"从 ERP/Excel 批量同步商品价格与库存"之类的工具中，配合 Transformations 将上游数据映射成上述结构后一次性提交。

删除语义与错误处理

• 源码中删除操作统一携带 force: true（如 operation.ts），意味着删除为永久删除而非移入回收站，执行前请确认目标 ID。
• 单个资源的读取/更新/删除都依赖对应的 ID 参数（customer_id / product_id / order_id），ID 可直接手填，也可以引用其它组件或查询的输出值。
• 请求失败时插件会返回接口错误体（error.response.data），你可以在查询结果中查看具体错误码与消息，据此修正 Data 结构或参数取值。

结果消费

列表操作在组装查询串后调用对应 GET 端点（operation.ts），成功时返回结果包含 statusCode 与数据体。在 ToolJet 中，你可以把订单/商品列表渲染到 Table 组件，把单条记录回填到表单组件用于编辑，或在按钮的点击事件中触发 create / update 操作——由此即可用纯可视化方式搭建出完整的电商后台运营工具。

常见问题排查

现象	原因与处理建议
保存数据源时报 Invalid credentials	Host、Consumer key 或 Consumer secret 有误，或密钥权限不足；请回到商店后台重新核对凭据
查询提示接口不存在	插件固定调用 wc/v3 版本，请确认商店 WooCommerce 版本及 REST API 已启用
返回结果不是期望的数组/对象	列表结果在 data 中，单条结果也在 data 中；结合 Transformations 将嵌套输出重塑为组件需要的结构
批量或写入操作返回 400	Data 结构与目标资源 Schema 不符，检查必填字段与字段名拼写

本文对应的官方文档原文位于 docs/docs/data-sources/woocommerce.md，插件完整实现位于 plugins/packages/woocommerce，如需定制新的操作或资源，可参照 operation.ts 与 manifest.json 扩展。