224 lines
No EOL
17 KiB
Markdown
224 lines
No EOL
17 KiB
Markdown
---
|
||
sidebar_label: Store API
|
||
category_slug: store-api
|
||
post_title: Store API
|
||
---
|
||
|
||
# WooCommerce Store API
|
||
|
||
**Store API 为面向客户的购物车、结账和产品功能的开发提供公开的 REST API 端点。它遵循 [WordPress REST API](https://developer.wordpress.org/rest-api/key-concepts/) 中使用的许多样板。**
|
||
|
||
与 WooCommerce REST API 不同，Store API 无需身份验证，并且不提供对敏感商店数据或其他客户信息的访问权限。
|
||
|
||
使用 cURL 的有效 API 请求示例：
|
||
|
||
```sh
|
||
curl "https://example-store.com/wp-json/wc/store/v1/products"
|
||
```
|
||
|
||
Store API 的可能用途包括：
|
||
|
||
1. 获取可显示、可搜索或过滤的产品列表
|
||
2. 将产品添加到购物车并返回已更新的购物车对象以供显示
|
||
3. 获取购物车的运输费率
|
||
4. 将客户的购物车转换为订单，收集地址，然后促进支付
|
||
|
||
## 要求与限制
|
||
|
||
* 这是一个无需认证的 API。访问时不需要 API 密钥或认证令牌。
|
||
* 所有 API 回复均返回 JSON 格式的数据。
|
||
* 从 API 返回的数据反映的是当前用户（客户）的信息。WooCommerce 中的客户会话是基于 Cookie 的。
|
||
* Store API 不能用于通过 ID 查找其他客户和订单；只能访问属于当前用户的数据。
|
||
* 同样，Store API 不能用于写入商店数据，例如设置。如需更广泛的访问权限，请使用经过认证的 [WC REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction)。
|
||
* 允许写入的端点（例如，更新当前客户地址）需要一个[随机数令牌](https://developer.wordpress.org/plugins/security/nonces/)。
|
||
* Store API 与渲染目标无关，不应对内容的显示位置做出假设。例如，除非数据类型本身是 HTML，否则不鼓励返回 HTML。
|
||
|
||
## 商店 API 命名空间
|
||
|
||
商店 API 中的所有资源都位于 `wc/store/v1` 命名空间内，并且由于此 API 扩展了 WordPress API，访问它需要 `/wp-json/` 基础路径。当前唯一的版本是 `v1`。如果省略版本，将提供 `v1` 版本。
|
||
|
||
例子：
|
||
|
||
```http
|
||
GET /wp-json/wc/store/v1/products
|
||
GET /wp-json/wc/store/v1/cart
|
||
```
|
||
|
||
该 API 使用 JSON 来序列化数据。您无需在 API 网址末尾指定 `.json`。
|
||
|
||
## 资源和端点
|
||
|
||
以下列出了商店 API 中可用的资源，并提供了指向更详细文档的链接。
|
||
|
||
## Installation
|
||
|
||
To install the package, use the following command:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```python
|
||
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](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.
|
||
|
||
| Resource | Methods | Endpoints |
|
||
| :----------------------------------------------------------- | :----------------------------- | --------------------------------------------------------------------------------------------- |
|
||
| [`Cart`](/docs/apis/store-api/resources-endpoints/cart) | `GET` | [`/wc/store/v1/cart`](/docs/apis/store-api/resources-endpoints/cart#get-cart) |
|
||
| | `POST` | [`/wc/store/v1/cart/add-item`](/docs/apis/store-api/resources-endpoints/cart#add-item) |
|
||
| | `POST` | [`/wc/store/v1/cart/remove-item`](/docs/apis/store-api/resources-endpoints/cart#remove-item) |
|
||
| | `POST` | [`/wc/store/v1/cart/update-item`](/docs/apis/store-api/resources-endpoints/cart#update-item) |
|
||
| | `POST` | [`/wc/store/v1/cart/apply-coupon`](/docs/apis/store-api/resources-endpoints/cart#apply-coupon) |
|
||
| | `POST` | [`/wc/store/v1/cart/remove-coupon`](/docs/apis/store-api/resources-endpoints/cart#remove-coupon) |
|
||
| | `POST` | [`/wc/store/v1/cart/update-customer`](/docs/apis/store-api/resources-endpoints/cart#update-customer) |
|
||
| | `POST` | [`/wc/store/v1/cart/select-shipping-rate`](/docs/apis/store-api/resources-endpoints/cart#select-shipping-rate) |
|
||
| [`Cart Items`](/docs/apis/store-api/resources-endpoints/cart-items) | `GET`, `POST`, `DELETE` | [`/wc/store/v1/cart/items`](/docs/apis/store-api/resources-endpoints/cart-items#list-cart-items) |
|
||
| | `GET`, `POST`, `PUT`, `DELETE` | [`/wc/store/v1/cart/items/:key`](/docs/apis/store-api/resources-endpoints/cart-items#single-cart-item) |
|
||
| [`Cart Coupons`](/docs/apis/store-api/resources-endpoints/cart-coupons) | `GET`, `POST`, `DELETE` | [`/wc/store/v1/cart/coupons`](/docs/apis/store-api/resources-endpoints/cart-coupons#list-cart-coupons) |
|
||
| | `GET`, `DELETE` | [`/wc/store/v1/cart/coupon/:code`](/docs/apis/store-api/resources-endpoints/cart-coupons#single-cart-coupon) |
|
||
| [`Checkout`](/docs/apis/store-api/resources-endpoints/checkout) | `GET`, `POST`, `PUT` | [`/wc/store/v1/checkout`](/docs/apis/store-api/resources-endpoints/checkout) |
|
||
| [`Checkout order`](/docs/apis/store-api/resources-endpoints/checkout-order) | `POST` | [`/wc/store/v1/checkout/:id`](/docs/apis/store-api/resources-endpoints/checkout-order) |
|
||
| [`Order`](/docs/apis/store-api/resources-endpoints/order) | `GET` | [`/wc/store/v1/order/:id`](/docs/apis/store-api/resources-endpoints/order) |
|
||
| [`Products`](/docs/apis/store-api/resources-endpoints/products) | `GET` | [`/wc/store/v1/products`](/docs/apis/store-api/resources-endpoints/products#list-products) |
|
||
| | `GET` | [`/wc/store/v1/products/:id`](/docs/apis/store-api/resources-endpoints/products#single-product-by-id) |
|
||
| [`Product Collection Data`](/docs/apis/store-api/resources-endpoints/product-collection-data) | `GET` | [`/wc/store/v1/products/collection-data`](/docs/apis/store-api/resources-endpoints/product-collection-data) |
|
||
| [`Product Attributes`](/docs/apis/store-api/resources-endpoints/product-attributes) | `GET` | [`/wc/store/v1/products/attributes`](/docs/apis/store-api/resources-endpoints/product-attributes#list-product-attributes) |
|
||
| | `GET` | [`/wc/store/v1/products/attributes/:id`](/docs/apis/store-api/resources-endpoints/product-attributes#single-product-attribute) |
|
||
| [`Product Attribute Terms`](/docs/apis/store-api/resources-endpoints/product-attribute-terms) | `GET` | [`/wc/store/v1/products/attributes/:id/terms`](/docs/apis/store-api/resources-endpoints/product-attribute-terms) |
|
||
| [`Product Categories`](/docs/apis/store-api/resources-endpoints/product-categories) | `GET` | [`/wc/store/v1/products/categories`](/docs/apis/store-api/resources-endpoints/product-categories) |
|
||
| [`Product Brands`](/docs/apis/store-api/resources-endpoints/product-brands) | `GET` | [`/wc/store/v1/products/brands`](/docs/apis/store-api/resources-endpoints/product-brands) |
|
||
| [`Product Reviews`](/docs/apis/store-api/resources-endpoints/product-reviews) | `GET` | [`/wc/store/v1/products/reviews`](/docs/apis/store-api/resources-endpoints/product-reviews) |
|
||
| [`Product Tags`](/docs/apis/store-api/resources-endpoints/product-tags) | `GET` | [`/wc/store/v1/products/tags`](/docs/apis/store-api/resources-endpoints/product-tags) |
|
||
|
||
## 分页
|
||
|
||
如果集合包含大量结果，则可能会进行分页。 在列出资源时，您可以传递以下参数：
|
||
|
||
| 参数 | 描述 |
|
||
| :------- | :------------------------------------------------------------------------------------- |
|
||
| `page` | 集合的当前页。 默认为 `1`。 |
|
||
| `per_page` | 结果集中返回的最大项目数。 默认为 `10`。 最大值为 `100`。 |
|
||
|
||
在下面的示例中，我们每页列出 20 个产品，并返回第 2 页。
|
||
|
||
```sh
|
||
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`（上级），如果适用。 |
|
||
|
||
## Status codes
|
||
|
||
The following table gives an overview of how the API functions generally behave.
|
||
|
||
| Request type | Description |
|
||
| :----------- | :---------------------------------------------------------------------------------------------------------- |
|
||
| `GET` | Access one or more resources and return `200 OK` and the result as JSON. |
|
||
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
|
||
| `PUT` | Return `200 OK` if the resource is modified successfully. The modified result is returned as JSON. |
|
||
| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. |
|
||
|
||
The following table shows the possible return codes for API requests.
|
||
|
||
| Response code | Description |
|
||
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `200 OK` | The request was successful, the resource(s) itself is returned as JSON. |
|
||
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
|
||
| `201 Created` | The POST request was successful and the resource is returned as JSON. |
|
||
| `400 Bad Request` | A required attribute of the API request is missing. |
|
||
| `403 Forbidden` | The request is not allowed. |
|
||
| `404 Not Found` | A resource could not be accessed, for example it doesn't exist. |
|
||
| `405 Method Not Allowed` | The request is not supported. |
|
||
| `409 Conflict` | The request could not be completed due to a conflict with the current state of the target resource. The current state may also be returned. |
|
||
| `500 Server Error` | While handling the request something went wrong server-side. |
|
||
|
||
## 贡献
|
||
|
||
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 核心原则](/docs/apis/store-api/guiding-principles)。 这涵盖了我们的开发方法，以及诸如版本控制、哪些数据可以包含以及如何构建新路由等主题。
|
||
|
||
## 可扩展性
|
||
|
||
Store API 的可扩展性是通过将某些路由和结构化数据暴露给 `ExtendSchema` 类来实现的。有关贡献者在此方面的文档，请访问 [此处](/docs/apis/store-api/extending-store-api)。
|
||
|
||
如果某个路由包含可扩展性界面，第三方开发者可以使用共享的 `ExtendSchema::class` 实例来注册额外的端点数据和额外的结构化数据。
|
||
|
||
这与传统的过滤器钩子方法不同，它更具限制性，但可以减少第三方扩展破坏现有路由和端点或覆盖其他应用程序可能依赖的返回数据的可能性。
|
||
|
||
如果需要新的结构化数据，并且以下任何一条语句为真，请选择 _扩展_ Store API，而不是向现有的 Store API 结构化数据中添加新的结构化数据：
|
||
|
||
* 数据是扩展的一部分，而不是核心功能。
|
||
* 数据与某个资源相关，但从技术上讲不是该资源的一部分。
|
||
* 数据难以查询（在性能方面），或者具有非常狭窄或特定的使用场景。
|
||
|
||
如果数据是敏感的（例如，一个核心设置，应该保持私有），或者与当前用户无关（例如，通过订单 ID 查找订单），请 [选择使用经过身份验证的 WC REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction)。
|
||
|
||
如果您想添加 _新的路由和端点_，而不是扩展 Store API 的 _结构化数据_，则无需扩展 Store API。 您可以使用 WordPress 的核心功能来创建新的路由，如果您希望，可以选择使用与 Store API 相同的模式。 参见：
|
||
|
||
* [`register_rest_route()`](https://developer.wordpress.org/reference/functions/register_rest_route/)
|
||
* [REST API 权限回调](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#permissions-callback) |
