WooCommerce REST API 文档

title: "简介 #" post_status: publish comment_status: open taxonomy: category: - woocommerce-rest-api post_tag: - Wp Api V2 - Includes - Source

简介

WooCommerce (WC) 2.6+ 已与 WordPress REST API 完全集成。这使得可以使用 JSON 格式的请求、WordPress REST API 认证方法以及大多数 HTTP 客户端都能理解的标准 HTTP 动词来创建、读取、更新和删除 WC 数据。

当前的 WP REST API 集成版本为 v2，它在端点中占据首要位置。

下表展示了每个 WooCommerce 主要版本中存在的 API 版本：

API 版本 WC 版本 WP 版本 文档
v2 3.0.x 或更高 4.4 或更高 -
v1 2.6.x 或更高 4.4 或更高 v1 文档

在 2.6 版本之前，WooCommerce 拥有一个独立于 WordPress 的 REST API，现在称为旧版 API。您可以单独找到旧版 API 的文档。

API 版本 WC 版本 WP 版本 文档
Legacy v3 2.4.x 或更高 4.1 或更高 Legacy v3 文档
Legacy v2 2.2.x 或更高 4.1 或更高 Legacy v2 文档
Legacy v1 2.1.x 或更高 4.1 或更高 Legacy v1 文档

要求

要使用最新版本的 REST API，您必须满足以下条件：

如果您使用 ModSecurity 并看到 501 方法未实现 错误，请参阅 此问题 了解详情。

请求/响应格式

默认响应格式为 JSON。包含消息体的请求使用纯 JSON 来设置或更新资源属性。成功的请求将返回 200 OK HTTP 状态码。

关于响应的一些通用信息：

JSONP 支持

WP REST API 默认支持 JSONP。JSONP 响应使用 application/javascript 内容类型。对于 GET 请求，您可以使用 ?_jsonp 参数指定回调函数，使响应包装在 JSON 函数中：

GET
/wp-json/wc/v2?_jsonp=callback
curl https://example.com/wp-json/wc/v2/products/tags/34?_jsonp=tagDetails \
    -u consumer_key:consumer_secret

WooCommerce.get("products/tags/34?_jsonp=tagDetails")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

<?php print_r($woocommerce->get('products/tags/34', ['_jsonp' => 'tagDetails'])); ?>

print(wcapi.get("products/tags/34?_jsonp=tagDetails").json())

woocommerce.get("products/tags/34", _jsonp: "tagDetails").parsed_response

响应示例：

/**/tagDetails({"id":34,"name":"Leather Shoes","slug":"leather-shoes","description":"","count":0,"_links":{"self":[{"href":"https://example.com/wp-json/wc/v2/products/tags/34"}],"collection":[{"href":"https://example.com/wp-json/wc/v2/products/tags"}]}})%

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code Error Type
400 Bad Request Invalid request, e.g. using an unsupported HTTP method
401 Unauthorized Authentication or permission error, e.g. incorrect API keys
404 Not Found Requests to resources that don't exist or are missing
500 Internal Server Error Server error

WP REST API error example:

{
  "code": "rest_no_route",
  "message": "No route was found matching the URL and request method",
  "data": {
    "status": 404
  }
}

WooCommerce REST API error example:

{
  "code": "woocommerce_rest_term_invalid",
  "message": "Resource doesn't exist.",
  "data": {
    "status": 404
  }
}

Errors return both an appropriate HTTP status code and response object which contains a code, message and data attribute.

参数

几乎所有端点都接受可选参数，可通过 HTTP 查询字符串参数传递，例如 GET /orders?status=completed。所有参数均随各端点文档一同说明。

分页

返回多个项目的请求默认会分页为每页 10 项。站点管理员可以通过修改 posts_per_page 选项来更改此默认值。或者，也可以通过 ?per_page 参数指定每页的项目数：

GET /orders?per_page=15

您可以使用 ?page 参数指定后续页面：

GET /orders?page=2

您还可以使用 ?offset 参数指定从第一个资源开始的偏移量：

GET /orders?offset=5

页码从 1 开始计数，省略 ?page 参数将返回第一页。

资源总数和总页数始终包含在 X-WP-Total 和 X-WP-TotalPages HTTP 头中。

链接头信息

分页信息包含在链接头信息中。建议您尽可能遵循这些值，而不是自行构建URL。

Link: <https://www.example.com/wp-json/wc/v2/products?page=2>; rel="next",
<https://www.example.com/wp-json/wc/v2/products?page=3>; rel="last"`

可能的 rel 值包括：

值 描述
next 显示下一页结果的URL。
last 显示最后一页结果的URL。
first 显示第一页结果的URL。
prev 显示上一页结果的URL。

Libraries and Tools

Official libraries

// Install:
// npm install --save @woocommerce/woocommerce-rest-api

// Setup:
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'http://example.com', // Your store URL
  consumerKey: 'consumer_key', // Your consumer key
  consumerSecret: 'consumer_secret', // Your consumer secret
  version: 'wc/v2' // WooCommerce WP REST API version
});

<?php
// Install:
// composer require automattic/woocommerce

// Setup:
require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'http://example.com', // Your store URL
    'consumer_key', // Your consumer key
    'consumer_secret', // Your consumer secret
    [
        'wp_api' => true, // Enable the WP REST API integration
        'version' => 'wc/v2' // WooCommerce WP REST API version
    ]
);
?>

# Install:
# pip install woocommerce

# Setup:
from woocommerce import API

wcapi = API(
    url="http://example.com", # Your store URL
    consumer_key="consumer_key", # Your consumer key
    consumer_secret="consumer_secret", # Your consumer secret
    wp_api=True, # Enable the WP REST API integration
    version="wc/v2" # WooCommerce WP REST API version
)

# Install:
# gem install woocommerce_api

# Setup:
require "woocommerce_api"

woocommerce = WooCommerce::API.new(
  "https://example.com", # Your store URL
  "consumer_key", # Your consumer key
  "consumer_secret", # Your consumer secret
  {
    wp_api: true, # Enable the WP REST API integration
    version: "wc/v2" # WooCommerce WP REST API version
  }
)

第三方库

工具

以下是一些可用于访问 API 的实用工具：