WooCommerce REST API： 集成、管理和故障排除指南

你的电商网站通常涉及高成本和大量的手动工作，例如定期更新库存或处理订单。而 WooCommerce REST API 能通过代码帮助管理员更高效地管理商店，减少这些任务。

用 API，可以自动化流程，将商店与其他工具连接，并处理日常任务，不需要手动操作。从更新产品详情到管理订单，REST API 能够通过简单的 HTTP 请求轻松完成这些操作。

在这篇文章中，介绍怎么集成 WooCommerce REST API，怎么测试它，以及如何使用它来管理产品，还会讲解在遇到问题时的故障排除步骤。

什么是 REST API，它是如何工作的？

REST API 是一种软件应用程序通过互联网相互通信的方式。它的全称是 Representational State Transfer（表述性状态转移），并遵循一套指导原则，使集成变得简单且具有可扩展性。

当客户端通过 REST API 向服务器请求信息时，服务器会以标准化的格式返回所请求资源的当前状态。REST API 用 HTTP 请求来执行标准的数据库功能，例如在资源中进行 CRUD（创建、读取、更新、删除）操作。

与 SOAP 等其他技术相比，REST 更受欢迎，因为它使用的带宽更少，更适合互联网环境。

我们之前也整理过一篇关于REST API的文章，具体详情可以参阅WooCommerce REST API 手册：全面解析和实战案例解析。

在 WooCommerce 中使用 REST API 的优势

在 WooCommerce 中用 REST API 有许多优势，包括：

• 支持多平台互操作性：REST API 允许多个平台之间的无缝通信。
• 提供开发灵活性：开发者可以根据需要灵活构建应用程序。
• 实现与不同设备的连接：通过 REST API，可以轻松连接各种设备。
• 简化数据同步：REST API 让数据同步变得轻而易举。
• 方便访问第三方内容：使用 REST API，可以快速集成和访问第三方内容。

用 WooCommerce REST API 的要求

要用 WooCommerce REST API，要满足下面这些条件：

1. WooCommerce 3.5 及以上版本
2. WordPress 4.4 及以上版本
3. 启用固定链接（路径：设置 > 固定链接）
4. 启用 HTTPS 以确保 API 访问安全（推荐）
5. 使用 Postman 或 Insomnia 测试 WooCommerce REST API

在本教程，会用最新版本的 WooCommerce 和 WordPress。确保 WordPress 固定链接是人类可读的（路径：设置 > 固定链接）。我将选择“文章名称”选项，但为了更好的兼容性，可以选择除“朴素”以外的任何格式。

步骤：

1. 前往 仪表盘 → 设置 → 固定链接。
2. 选择“文章名称”选项，并点击底部的“保存更改”按钮。

如何集成 WooCommerce REST API？

API 是一种工具，能够让不同的软件应用程序相互通信。例如，像 PayPal 这样的支付网关通过 API 与电商网站连接，从而安全地处理交易，不需要自行构建支付功能。

WooCommerce REST API 能读取和写入商店中的数据，包括订单、产品和客户。例如，如果经营一个在线服装店网站，可以通过 API 在产品售罄时自动更新库存。

使用 WooCommerce API，按照下面步骤操作：

步骤 1：设置并访问 WooCommerce API

要使用 WooCommerce API，首先需要在网站上安装 WooCommerce。没有网站的，可以参考我们的教程创建：

新手也能快速上手：阿里云+宝塔面板打造WordPress网站全攻略

在腾讯云上使用1Panel手动安装WordPress的超详细保姆级教程

WooCommerce 网站准备好后，需要生成 API 密钥以验证 API 请求。操作步骤如下：

• 前往 WooCommerce 设置页面，点击 “高级” 标签，然后选择 “REST API”。

• 在这里，可以为需要 API 访问权限的每个用户生成密钥。

接下来，需要选择一个 API 端点。WooCommerce 提供多个端点来访问不同类型的数据，例如订单、产品、客户等。选择与您想要访问或修改的数据对应的端点。

到目前为止，完成了这些步骤：安装 WooCommerce、生成 API 密钥，并选择了正确的端点访问或修改商店中的数据。

步骤 2：在 WooCommerce 中创建 API 密钥

在步骤 1 中，我们已经设置了 WooCommerce 并准备好了 API 环境。现在，在步骤 2 中，需要生成 API 密钥。这一步非常关键，因为 API 密钥将用于验证对商店数据的所有请求，无论是检索订单、更新产品，还是管理客户。

在 WooCommerce 中创建 API 密钥的过程非常简单，几个步骤：

• 登录到 WordPress 仪表盘。
• 前往 WooCommerce → 设置。

• 单击“高级”选项卡，然后单击“REST API”选项卡。

• 单击添加密钥/创建 API 密钥按钮来创建新的 API 密钥。

在 描述 字段中输入 API 密钥的描述。

从 用户 下拉列表中选择要与该 API 密钥关联的用户。如果未看到想用的用户，可能需要先创建一个新用户。

从 权限 下拉列表中选择要赋予该 API 密钥的权限。可以选择以下权限类型：

• 读写权限（Read/Write）
• 只读权限（Read-only）
• 只写权限（Write-only）

• 单击生成 API 密钥按钮来生成 API 密钥。

确保将 Consumer Key 和 Consumer Secret 的值复制并保存在安全的地方，因为你将无法再次查看它们。

这样就成功在 WooCommerce 商店创建了 API 密钥，可以通过编程方式访问和操作商店的数据。

步骤 3：测试 WooCommerce 中的 REST API 是否正常工作

接下来，需要测试 REST API 是否正常工作。按照以下步骤验证 REST API 端点的功能：

启用旧版 REST API
第一步是启用旧版 REST API。在 WooCommerce 9.0 之前，可以通过前往 设置 → 高级，启用旧版 API 选项。然而，现在需要安装一个名为 WooCommerce Legacy REST API 的专用扩展插件。

安装完成后，再次查看旧版 API 选项，会看到 “旧版 REST API 已启用” 的复选标记。

下一步是在 API 平台上进行测试。会在两个 API 测试平台上测试 REST API：Postman和Insomnia。

在 Postman 中测试 WooCommerce REST API

Postman 是一个用于构建和使用 API 的平台。要在 Postman 中测试 API，首先需要注册一个账户。

我们将测试的请求 URL 为 wp-json/wc/v3/orders。在我的网站中，完整的 URL 类似于：
https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/orders。需要将其修改为你们自己网站的 URL。

成功登录到 Postman 后，按照以下步骤进行 REST API 测试：

1. 打开一个新标签页，访问 WooCommerce REST API 文档。
2. 在浏览器的另一个标签页中打开 Postman。
3. 前往 WooCommerce REST API 文档并搜索 Orders（订单）。
4. 从文档右侧面板中复制代码。
5. 参考下方截图进行操作。

为了方便跟随本教程操作，下面是需要复制的代码：

curl -X POST https://example.com/wp-json/wc/v3/orders \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}'

• 复制代码后，返回Postman选项卡。
• 单击“收藏夹”，然后单击“导入”。

• 粘贴从WooCommerce REST API文档复制的订单代码，然后单击“导入到集合”按钮。

• 选择请求类型为GET。

• 编辑请求 URL用自己的站点 URL。

• 现在选择Auth Type。为此，选择Basic Auth。
• 在用户名和密码字段中输入WooCommerce 中的消费者密钥和消费者密钥。如果还记得的话，这就是在步骤 2 结束时保存的内容。最后，单击“发送”按钮。

• 如果已正确设置 WooCommerce 商店并启用了 REST API 和生成了 API 密钥，则应该会看到一个 JSON 响应，其中包含商店中的产品列表。响应应如下所示：

在 Insomnia 上测试 WooCommerce REST API

用来测试 REST API 的第二个平台是Insomnia。为此，首先需要在系统上安装 Insomnia。安装后，按照下面步骤执行 REST API 测试。

• 单击“新收藏”。

• 给你的收藏命名。

• 单击“新建 HTTP 请求”。

• 选择请求类型为GET。

• 编辑请求 URL以使用您自己的站点 URL。

• 对于授权，选择基本授权。

• 在用户名和密码字段中输入来自 WooCommerce 的消费者密钥和消费者密钥。

• 点击发送按钮。在右侧面板中查看JSON 格式的结果。

如果收到类似这样的响应，恭喜！REST API 正常运行了。
如果遇到错误，仔细检查 API 凭据，以及是否已在 WooCommerce 中正确启用了 REST API。

WooCommerce REST API 如何工作？

WooCommerce REST API 基于 REST（表述性状态转移）的原则，能使用标准 HTTP 方法与商店数据（如订单、产品和客户）进行交互：

• GET：检索数据（例如获取订单列表）
• POST：创建新数据（例如添加新产品）
• PUT：更新现有数据（例如更改订单状态）
• DELETE：删除数据（例如删除客户）

每次交互都是通过端点完成的，这些端点是表示特定资源的结构化 URL。例如，要检索一个订单，可以使用端点 /wp-json/wc/v3/orders/{order_id}。这些端点基于资源结构，意味着每个 URL 都代表系统中的一种特定数据类型。

API 采用无状态通信，意味着每次从客户端到服务器的请求都必须包含服务器完成该请求所需的所有信息。

数据通常以 JSON 格式交换，这在 Web 应用程序中处理数据变得简单。每个 API 请求都必须经过身份验证，通常使用 API 密钥（可以在 WooCommerce 中生成）或其他方法（如 OAuth）。

API 支持各种测试和集成工具，例如 Postman 和 Insomnia，它们可以轻松发送请求并查看响应。

对于大多数用户，与外部服务的集成非常简单，通常只需生成 API 密钥并与外部服务共享以建立连接。一旦连接成功，外部服务就可以用提供的 API 与 WooCommerce 商店交互。

如何通过 REST API 管理产品（添加/编辑/删除）

在上一部分中，已经使用 Postman 和 Insomnia 测试了 WooCommerce 的 REST API。现在，可以用它来管理商店中的产品。

WooCommerce 使用 产品对象 来管理商店中的产品。这些对象包含多种属性，例如 price（价格）、stock_status（库存状态）和 grouped_products（分组产品）。这些属性能让管理员通过 API 轻松控制库存、定价和产品分类等内容。

例如，要将产品分配到一个分组中，只需使用该分组的 ID 配合 grouped_products 属性即可。

在管理库存时，有两个关键属性：

1. manage_stock：设置为 true 或 false，启用或禁用库存管理。

2. stock_status：用于反映产品当前状态，可选值包括：

• instock（有库存）
• onbackorder（接受预定）
• outofstock（无库存）

接下来，我们了解如何以编程方式添加或更新产品详情。

通过 WooCommerce API 添加产品

要用 Postman 将产品添加到我们的商店，需要将请求方法从 GET 切换为 POST，并将端点 URL 更改为：
https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/products

操作步骤：

1. 前往 Postman 的 Body 选项卡。
2. 选择 Raw 选项，并将格式设置为 JSON。
3. 替换现有代码，使用以下 JSON 数据：

{
  "name": "Macbook Pro M3",
  "type": "simple",
  "description": "The M3 chip features 8 CPU cores, 10 GPU cores, and a 16-core neural engine for enhanced performance.",
  "short_description": "",
  "categories": [],
  "tags": [],
  "images": []
}

这个 JSON 包含了产品的详细信息，例如名称、类型、描述，以及可选字段如类别、标签和图片。

输入完数据后，点击 发送 按钮。如果产品成功创建，会收到包含产品对象的响应。

这是添加到商店的产品：

通过 WooCommerce API 编辑产品

假设对之前添加的产品不满意，想要编辑它——用 WooCommerce API 也可以做到这一点。只需要知道之前添加到商店中的产品的 ID。在我的例子中，产品的 id 是 28。

在本教程中，我们更改之前添加的产品名称。操作步骤如下：

修改 JSON 数据，像这样：

{
  "name": "Macbook Air M3"
}

注意：我们没有包含其他属性，因为我们只是想更改产品名称。并且由于不需要添加新产品，只需要修改现有产品，所以我们将端点 URL 更改为：

https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/products<your-id-here>。

在例子中，产品的 ID 是 28，所以 URL 是：

https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/products/28。

接下来，将请求方法更改为 PUT，并运行该请求。可以通过检查商店中更新后的产品名称来确认更新是否成功。

这是我们商店中更新的产品名称：

通过 WooCommerce API 删除产品

要删除产品，我们用 DELETE 请求方法。会删除之前在商店中更新的 Macbook Air M3 – Updated 产品。操作步骤如下：

用与之前相同的端点 URL，但将请求类型更改为 DELETE。

在端点 URL 中输入产品的 ID，然后点击 发送。

产品会从商店中删除，如下所示：

如何通过 REST API 管理订单（获取/更新订单状态）

WooCommerce REST API 通过自动化任务（如获取和更新订单状态）简化了订单处理。可以轻松地：

• 获取订单并根据日期、状态或客户进行筛选。
• 更新订单状态，反映不同的阶段，例如“已完成”。
• 管理退款，包括处理请求并自动处理退款。

接下来，看看如何获取最近的订单并将订单状态更新为“已完成”。

获取订单

在这个例子中，我们会获取最近的订单，然后将其状态更新为“已完成”。要获取最近的订单，需要一个日期范围，并且需要使用 GET 请求。

下面是我用 Postman 获取最近订单的方法：

1. 首先，将端点 URL 更新为 https:///wp-json/wc/v3/orders。 URL 看起来是这样的：
   https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/orders
2. 接下来，由于需要获取最近的订单 ID，我会提供一个日期范围，并使用 after 参数仅获取今天之后的订单。在我的例子中，日期范围为 2024-09-08T00:00:00。我的 URL 看起来像这样：
   https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/orders?after=2024-09-08T00:00:00

修改 URL 后，前往 Params 选项卡，并在 Value 字段中添加日期，如下图所示：

运行请求后，可以看到与提供的日期条件匹配的商店最近订单列表。

在我的例子中，订单 ID 是 “id”: 25，状态是 “pending”。我们将其更改为 “completed”，好吗？

更新订单状态

要更新订单状态，我们用 PUT 请求方法。还需要修改端点 URL，包含特定的订单 ID。在这个例子中，订单 ID 是 25，所以 URL 将是：

https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/orders/25

接下来，前往 Body 选项卡，并添加以下 JSON 数据：

{
  "status": "completed"
}

运行这个请求会把订单状态更新为 已完成，如下所示：

如何通过 REST API 管理客户（添加/检索客户 ID）

通过 WooCommerce REST API，客户管理和互动变得更加简便。

企业可以：

• 创建和更新客户资料。
• 检索客户信息，如购买历史和偏好设置。
• 使用这些数据进行个性化营销、发送定向促销和推荐产品。

这帮助企业更好地与客户互动，促进重复购买。

添加客户

要添加客户，要用 POST 请求方法，并将端点 URL 更改为：
https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/customers

接下来，在 Body 选项卡中，用以下 JSON 来创建新客户：

{
  "email": "a.rehman@gmail.com",
  "first_name": "Abdul",
  "last_name": "Rehman",
  "role": "customer",
  "username": "abdul.rehman",
  "billing": {
    "first_name": "Abdul",
    "last_name": "Rehman",
    "company": "",
    "address_1": "123 Main Street",
    "address_2": "",
    "city": "Lahore",
    "state": "Punjab",
    "postcode": "54000",
    "country": "PK",
    "email": "a.rehman@gmail.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "Abdul",
    "last_name": "Rehman",
    "company": "",
    "address_1": "123 Main Street",
    "address_2": "",
    "city": "Lahore",
    "state": "Punjab",
    "postcode": "54000",
    "country": "PK"
  }
}

运行请求后，会收到包含客户详细信息的响应。一定要记录客户的 ID，因为在下一部分中需要它来检索该客户的详细信息。

可以看到，添加了新的客户信息，客户ID为“id”: 2。

通过 ID 检索客户信息

现在，我们用 GET 请求方法，根据之前创建的客户 ID 检索客户信息。在我的例子中，客户 ID 是 “2”。

在端点 URL 中添加客户 ID，格式如下：
https://<mydomain>/wp-json/wc/v3/customers/<customer-id>

我的端点 URL 如下：
https://woocommerce-1146547-3986789.cloudwaysapps.com/wp-json/wc/v3/customers/2

运行请求后，可以看到该客户的详细信息，如下所示：

WooCommerce REST API 可用端点

WooCommerce REST API 通过端点提供对商店不同部分的访问。端点是执行各种商店功能的特定 URL。例如，通过 /wp-json/wc/v3/products 端点，可以检索、创建或更新商店中的产品。

下面是关键端点的列表，以及相应的 PHP 示例代码片段：

总结

总的来说，WooCommerce REST API 是一个非常适合希望提升线上业务的用户工具。它可以将商店与其他应用程序连接，并自动化工作流程，从而通过优化流程节省时间和精力。