woocommerce/docs/apis/store-api

title	post_status	comment_status	taxonomy
WooCommerce 商店 API	publish	open	category post_tag woocommerce Store Api Apis Repos

WooCommerce 商店 API

商店 API 提供了面向客户的购物车、结账和产品功能的公共 REST API 接口。它遵循了 WordPress REST API 中许多模式。

与 WooCommerce REST API 相比，商店 API 不进行身份验证，并且不提供对敏感商店数据或其他客户信息的访问。

以下是使用 cURL 的有效 API 请求示例：

curl "https://example-store.com/wp-json/wc/store/v1/products"

商店 API 的可能用途包括：

1. 获取产品列表以进行显示，这些产品可以被搜索或过滤。
2. 将产品添加到购物车，并返回更新后的购物车对象以进行显示。
3. 获取购物车的配送费用。
4. 将客户的购物车转换为订单，收集地址，然后促进支付。

需求和限制

• 这是一个未经身份验证的 API。 访问它不需要 API 密钥或身份验证令牌。
• 所有 API 响应都返回 JSON 格式的数据。
• 从 API 返回的数据反映了当前用户（客户）。 WooCommerce 中的客户会话基于 Cookie。
• 商店 API 不能用于通过 ID 查找其他客户和订单； 只能访问属于当前用户的的数据。
• 同样，商店 API 不能用于写入商店数据，例如设置。 要获得更广泛的访问权限，请使用经过身份验证的 WC REST API.
• 允许写入的端点，例如更新当前客户的地址，需要一个 随机数。
• 商店 API 不依赖于渲染目标，并且不应对内容将显示在哪里做出任何假设。 例如，除非数据类型本身是 HTML，否则不建议返回 HTML。

商店 API 命名空间

商店 API 中的资源都位于 wc/store/v1 命名空间中，并且由于此 API 扩展了 WordPress API，因此访问它需要 /wp-json/ 基础。 目前，唯一的版本是 v1。 如果省略版本，将提供 v1。

示例：

GET /wp-json/wc/store/v1/products
GET /wp-json/wc/store/v1/cart

API 使用 JSON 序列化数据。 您无需在 API URL 的末尾指定 .json。

资源和端点

以下列出了商店 API 中可用的资源，并提供了指向更详细文档的链接。

Installation

To install the package, use the following command:

pip install %s

This will install the package and all of its dependencies.

Usage

The package provides a simple API for interacting with the service. Here's a basic example:

import %s

# Create a new client
client = %s.Client()

# Call the API
response = client.get_data(%s)

# Print the response
print(response)

Documentation

For more information, please refer to the documentation: https://example.com/documentation.

API Reference

The following is a list of available API endpoints:

• GET /users: Retrieves a list of all users.
• GET /users/{id}: Retrieves a specific user by ID.
• POST /users: Creates a new user.
• PUT /users/{id}: Updates an existing user.
• DELETE /users/{id}: Deletes a user.

Contributing

We welcome contributions from the community. If you'd like to contribute, please follow the guidelines in the contributing document.

License

This package is licensed under the MIT License. See the LICENSE file for more information.

Troubleshooting

If you're having trouble with the package, please check the following:

• Make sure you have the latest version of the package installed.
• Check the logs for any errors.
• Consult the FAQ for common issues and solutions.

If you're still having trouble, please contact us for support.

规则:

1. 翻译所有英文文本，包括标题、段落、列表项
2. 保持 Markdown 格式不变（#、**、``、 等）
3. 代码块（...）内的代码不翻译，只翻译代码块外的文本
4. 保留所有占位符（%s, %d, {name}）和 HTML 标签
5. 保留所有 URL 链接地址不翻译
6. 函数名、变量名、命令名保留英文原文
7. 只输出翻译结果，不要输出解释或原文

术语表（必须使用以下译法）:

• Category → 分类
• API → API
• Tag → 标签
• Product Attributes → 产品属性
• Product Tags → 产品标签
• Attribute → 属性
• Resources → 资源
• Shipping → 配送
• Checkout → 结账
• Product → 产品
• Reviews → 评论
• Delete → 删除
• Remove → 移除
• Select → 选择
• Method → 方法
• Coupon → 优惠券
• Brand → 品牌
• check → 检查
• Store → 商店
• Order → 订单

资源	方法	接口
Cart	GET	/wc/store/v1/cart
	POST	/wc/store/v1/cart/add-item
	POST	/wc/store/v1/cart/remove-item
	POST	/wc/store/v1/cart/update-item
	POST	/wc/store/v1/cart/apply-coupon
	POST	/wc/store/v1/cart/remove-coupon
	POST	/wc/store/v1/cart/update-customer
	POST	/wc/store/v1/cart/select-shipping-rate
Cart Items	GET, POST, DELETE	/wc/store/v1/cart/items
	GET, POST, PUT, DELETE	/wc/store/v1/cart/items/:key
Cart Coupons	GET, POST, DELETE	/wc/store/v1/cart/coupons
	GET, DELETE	/wc/store/v1/cart/coupon/:code
Checkout	GET, POST, PUT	/wc/store/v1/checkout
Checkout order	POST	/wc/store/v1/checkout/:id
Order	GET	/wc/store/v1/order/:id
Products	GET	/wc/store/v1/products
	GET	/wc/store/v1/products/:id
Product Collection Data	GET	/wc/store/v1/products/collection-data
Product Attributes	GET	/wc/store/v1/products/attributes
	GET	/wc/store/v1/products/attributes/:id
Product Attribute Terms	GET	/wc/store/v1/products/attributes/:id/terms
Product Categories	GET	/wc/store/v1/products/categories
Product Brands	GET	/wc/store/v1/products/brands
Product Reviews	GET	/wc/store/v1/products/reviews
Product Tags	GET	/wc/store/v1/products/tags

分页

如果集合包含大量结果，则可能会进行分页。 在列出资源时，您可以传递以下参数：

参数	描述
page	集合的当前页。 默认为 1。
per_page	结果集中返回的最大项目数。 默认为 10。 最大值为 100。

在下面的示例中，我们每页列出 20 个产品，并返回第 2 页。

curl "https://example-store.com/wp-json/wc/store/v1/products?page=2&per_page=20"

此外，还会发送额外的分页头部，其中包含其它信息。

头部	描述
X-WP-Total	集合中项目的总数。
X-WP-TotalPages	集合中页面的总数。
Link	包含指向其他页面的链接；next（下一页）、prev（上一页）和 up（上级），如果适用。

状态码

以下表格概括了 API 函数的一般行为。

请求类型	描述
GET	访问一个或多个资源，并返回 200 OK 以及结果以 JSON 格式。
POST	如果资源创建成功，则返回 201 Created，并将新创建的资源以 JSON 格式返回。
PUT	如果资源修改成功，则返回 200 OK。修改后的结果以 JSON 格式返回。
DELETE	如果资源已成功删除，则返回 204 No Content。

以下表格显示了 API 请求可能返回的代码。

响应代码	描述
200 OK	请求成功，资源本身以 JSON 格式返回。
204 No Content	服务器已成功处理请求，并且响应内容体中没有额外的内容需要发送。
201 Created	POST 请求成功，资源以 JSON 格式返回。
400 Bad Request	API 请求缺少必需的属性。
403 Forbidden	请求被拒绝。
404 Not Found	无法访问资源，例如资源不存在。
405 Method Not Allowed	请求不受支持。
409 Conflict	由于与目标资源的当前状态冲突，无法完成请求。当前状态也可能被返回。
500 Server Error	在处理请求时，服务器端出现错误。

贡献

Store API 中的每个路由主要包含 3 个部分：

1. 路由 (Route) - 负责将请求映射到端点。Store API 中的路由扩展 AbstractRoute 类；该类包含处理请求和返回 JSON 回复的共享功能。路由确保返回有效的回复，并处理集合、错误和分页。
2. 结构化数据 (Schema) - 路由不负责格式化资源。我们使用 结构化数据 类来表示每种类型的资源，例如，一个产品、一个购物车或一个购物车项目。Store API 中的结构化数据类应扩展 AbstractSchema 类。
3. 实用工具 (Utility) - 在更高级的场景中，当 Store API 需要访问 WooCommerce 核心中的复杂数据，或者多个路由需要访问相同的数据时，路由应使用控制器或实用工具类。例如，Store API 具有订单控制器和购物车控制器，分别用于查找订单和购物车数据。

通常，路由处理以下类型的请求：

• GET 请求用于读取产品、购物车或结账数据。
• POST 和 PUT 请求用于更新购物车和结账数据。
• DELETE 请求用于移除购物车数据。
• OPTIONS 请求用于检索当前路由的 JSON 结构化数据。

请查看 Store API 核心原则。 这涵盖了我们的开发方法，以及诸如版本控制、哪些数据可以包含以及如何构建新路由等主题。

可扩展性

Store API 的可扩展性是通过将某些路由和结构化数据暴露给 ExtendSchema 类来实现的。有关贡献者在此方面的文档，请访问 此处。

如果某个路由包含可扩展性界面，第三方开发者可以使用共享的 ExtendSchema::class 实例来注册额外的端点数据和额外的结构化数据。

这与传统的过滤器钩子方法不同，它更具限制性，但可以减少第三方扩展破坏现有路由和端点或覆盖其他应用程序可能依赖的返回数据的可能性。

如果需要新的结构化数据，并且以下任何一条语句为真，请选择 扩展 Store API，而不是向现有的 Store API 结构化数据中添加新的结构化数据：

• 数据是扩展的一部分，而不是核心功能。
• 数据与某个资源相关，但从技术上讲不是该资源的一部分。
• 数据难以查询（在性能方面），或者具有非常狭窄或特定的使用场景。

如果数据是敏感的（例如，一个核心设置，应该保持私有），或者与当前用户无关（例如，通过订单 ID 查找订单），请 选择使用经过身份验证的 WC REST API。

如果您想添加 新的路由和端点，而不是扩展 Store API 的 结构化数据，则无需扩展 Store API。 您可以使用 WordPress 的核心功能来创建新的路由，如果您希望，可以选择使用与 Store API 相同的模式。 参见：

• register_rest_route()
• REST API 权限回调