ClawSkills logoClawSkills

WooCommerce

具有托管 OAuth 功能的 WooCommerce REST API 集成。访问产品、订单、客户、优惠券、配送、税收、报告和 Webhooks。当用户 us

访问网站

介绍

# WooCommerce

通过托管的 OAuth 身份验证访问 WooCommerce REST API。管理产品、订单、客户、优惠券、配送、税收以及电子商务运营相关的更多内容。

## 快速开始

```bash # List products python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

## 基础 URL

``` https://gateway.maton.ai/woocommerce/{native-api-path} ```

将 `{native-api-path}` 替换为实际的 WooCommerce API 端点路径。网关会将请求代理到您的 WooCommerce 商店，并自动处理身份验证。

## 身份验证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

``` Authorization: Bearer $MATON_API_KEY ```

**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：

```bash export MATON_API_KEY="YOUR_API_KEY" ```

### 获取 API 密钥

1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 访问 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥

## 连接管理

在 `https://ctrl.maton.ai` 管理您的 WooCommerce OAuth 连接。

### 列出连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=woocommerce&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 创建连接

```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'woocommerce'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 获取连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "woocommerce", "metadata": {} } } ```

在浏览器中打开返回的 `url` 以完成 OAuth 授权。

### 删除连接

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 指定连接

如果您有多个 WooCommerce 连接，请使用 `Maton-Connection` 头指定要使用的连接：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

如果省略，网关将使用默认（最旧）的活动连接。

## API 参考

### Products (产品)

#### List All Products (列出所有产品)

```bash GET /woocommerce/wp-json/wc/v3/products ```

查询参数： - `page` - 当前页码（默认：1） - `per_page` - 每页项目数（默认：10，最大：100） - `search` - 按产品名称搜索 - `status` - 按状态筛选：`draft`（草稿）、`pending`（待定）、`private`（私密）、`publish`（已发布） - `type` - 按类型筛选：`simple`（简单）、`grouped`（分组）、`external`（外部）、`variable`（变量） - `sku` - 按 SKU 筛选 - `category` - 按分类 ID 筛选 - `tag` - 按标签 ID 筛选 - `featured` - 筛选特色产品 - `on_sale` - 筛选在售产品 - `min_price` / `max_price` - 按价格范围筛选 - `stock_status` - 按库存状态筛选：`instock`（有货）、`outofstock`（缺货）、`onbackorder`（缺货预订） - `orderby` - 排序依据：`date`（日期）、`id`（ID）、`include`（包含）、`title`（标题）、`slug`（别名）、`price`（价格）、`popularity`（人气）、`rating`（评分） - `order` - 排序顺序：`asc`（升序）、`desc`（降序）

**示例：**

```bash curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products?per_page=20&status=publish" -H "Authorization: Bearer $MATON_API_KEY" ```

**响应：** ```json [ { "id": 123, "name": "Premium T-Shirt", "slug": "premium-t-shirt", "type": "simple", "status": "publish", "sku": "TSH-001", "price": "29.99", "regular_price": "34.99", "sale_price": "29.99", "stock_quantity": 50, "stock_status": "instock", "categories": [{"id": 15, "name": "Apparel"}], "images": [{"id": 456, "src": "https://..."}] } ] ```

#### Get a Product (获取单个产品)

```bash GET /woocommerce/wp-json/wc/v3/products/{id} ```

**示例：**

```bash curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products/123" -H "Authorization: Bearer $MATON_API_KEY" ```

#### Create a Product (创建产品)

```bash POST /woocommerce/wp-json/wc/v3/products Content-Type: application/json

{ "name": "New Product", "type": "simple", "regular_price": "49.99", "description": "Full product description", "short_description": "Brief description", "sku": "PROD-001", "manage_stock": true, "stock_quantity": 100, "categories": [{"id": 15}], "images": [{"src": "https://example.com/image.jpg"}] } ```

**示例：**

```bash curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"name": "Premium Widget", "type": "simple", "regular_price": "19.99", "sku": "WDG-001"}' ```

#### Update a Product (更新产品)

```bash PUT /woocommerce/wp-json/wc/v3/products/{id} ```

**示例：**

```bash curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products/123" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"regular_price": "24.99", "sale_price": "19.99"}' ```

#### Delete a Product (删除产品)

```bash DELETE /woocommerce/wp-json/wc/v3/products/{id} ```

查询参数： - `force` - 设置为 `true` 以永久删除（默认：`false` 移至回收站）

#### Duplicate a Product (复制产品)

```bash POST /woocommerce/wp-json/wc/v3/products/{id}/duplicate ```

### Product Variations (产品变体)

对于可变产品，管理单个变体：

#### List Variations (列出变体)

```bash GET /woocommerce/wp-json/wc/v3/products/{product_id}/variations ```

#### Create Variation (创建变体)

```bash POST /woocommerce/wp-json/wc/v3/products/{product_id}/variations Content-Type: application/json

{ "regular_price": "29.99", "sku": "TSH-001-RED-M", "attributes": [ {"id": 1, "option": "Red"}, {"id": 2, "option": "Medium"} ] } ```

#### Update Variation (更新变体)

```bash PUT /woocommerce/wp-json/wc/v3/products/{product_id}/variations/{id} ```

#### Delete Variation (删除变体)

```bash DELETE /woocommerce/wp-json/wc/v3/products/{product_id}/variations/{id} ```

#### Batch Update Variations (批量更新变体)

```bash POST /woocommerce/wp-json/wc/v3/products/{product_id}/variations/batch ```

### Product Attributes (产品属性)

#### List Attributes (列出属性)

```bash GET /woocommerce/wp-json/wc/v3/products/attributes ```

#### Create Attribute (创建属性)

```bash POST /woocommerce/wp-json/wc/v3/products/attributes Content-Type: application/json

{ "name": "Color", "slug": "color", "type": "select", "order_by": "menu_order" } ```

#### Get/Update/Delete Attribute (获取/更新/删除属性)

```bash GET /woocommerce/wp-json/wc/v3/products/attributes/{id} PUT /woocommerce/wp-json/wc/v3/products/attributes/{id} DELETE /woocommerce/wp-json/wc/v3/products/attributes/{id} ```

### Attribute Terms (属性术语)

```bash GET /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms POST /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms GET /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id} PUT /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id} DELETE /woocommerce/wp-json/wc/v3/products/attributes/{attribute_id}/terms/{id} ```

### Product Categories (产品分类)

#### List Categories (列出分类)

```bash GET /woocommerce/wp-json/wc/v3/products/categories ```

#### Create Category (创建分类)

```bash POST /woocommerce/wp-json/wc/v3/products/categories Content-Type: application/json

{ "name": "Electronics", "parent": 0, "description": "Electronic products" } ```

#### Get/Update/Delete Category (获取/更新/删除分类)

```bash GET /woocommerce/wp-json/wc/v3/products/categories/{id} PUT /woocommerce/wp-json/wc/v3/products/categories/{id} DELETE /woocommerce/wp-json/wc/v3/products/categories/{id} ```

### Product Tags (产品标签)

```bash GET /woocommerce/wp-json/wc/v3/products/tags POST /woocommerce/wp-json/wc/v3/products/tags GET /woocommerce/wp-json/wc/v3/products/tags/{id} PUT /woocommerce/wp-json/wc/v3/products/tags/{id} DELETE /woocommerce/wp-json/wc/v3/products/tags/{id} ```

### Product Shipping Classes (产品配送类)

```bash GET /woocommerce/wp-json/wc/v3/products/shipping_classes POST /woocommerce/wp-json/wc/v3/products/shipping_classes GET /woocommerce/wp-json/wc/v3/products/shipping_classes/{id} PUT /woocommerce/wp-json/wc/v3/products/shipping_classes/{id} DELETE /woocommerce/wp-json/wc/v3/products/shipping_classes/{id} ```

### Product Reviews (产品评论)

#### List Reviews (列出评论)

```bash GET /woocommerce/wp-json/wc/v3/products/reviews ```

查询参数： - `product` - 按产品 ID 筛选 - `status` - 按状态筛选：`approved`（已批准）、`hold`（保留）、`spam`（垃圾）、`trash`（回收站）

#### Create Review (创建评论)

```bash POST /woocommerce/wp-json/wc/v3/products/reviews Content-Type: application/json

{ "product_id": 123, "review": "Great product!", "reviewer": "John Doe", "reviewer_email": "[email protected]", "rating": 5 } ```

#### Get/Update/Delete Review (获取/更新/删除评论)

```bash GET /woocommerce/wp-json/wc/v3/products/reviews/{id} PUT /woocommerce/wp-json/wc/v3/products/reviews/{id} DELETE /woocommerce/wp-json/wc/v3/products/reviews/{id} ```

---

### Orders (订单)

#### List All Orders (列出所有订单)

```bash GET /woocommerce/wp-json/wc/v3/orders ```

查询参数： - `page` - 当前页码（默认：1） - `per_page` - 每页项目数（默认：10） - `search` - 搜索订单 - `after` / `before` - 按日期筛选 (ISO8601) - `status` - 订单状态（见下文） - `customer` - 按客户 ID 筛选 - `product` - 按产品 ID 筛选 - `orderby` - 排序依据：`date`（日期）、`id`（ID）、`include`（包含）、`title`（标题）、`slug`（别名） - `order` - 排序顺序：`asc`（升序）、`desc`（降序）

**订单状态：** - `pending` - 等待付款 - `processing` - 已收到付款，等待履行 - `on-hold` - 等待付款确认 - `completed` - 订单已完成 - `cancelled` - 由管理员或客户取消 - `refunded` - 已全额退款 - `failed` - 付款失败

**示例：**

```bash curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders?status=processing&per_page=50" -H "Authorization: Bearer $MATON_API_KEY" ```

**响应：** ```json [ { "id": 456, "status": "processing", "currency": "USD", "total": "129.99", "customer_id": 12, "billing": { "first_name": "John", "last_name": "Doe", "email": "[email protected]" }, "line_items": [ { "id": 789, "product_id": 123, "name": "Premium T-Shirt", "quantity": 2, "total": "59.98" } ] } ] ```

#### Get an Order (获取单个订单)

```bash GET /woocommerce/wp-json/wc/v3/orders/{id} ```

#### Create an Order (创建订单)

```bash POST /woocommerce/wp-json/wc/v3/orders Content-Type: application/json

{ "payment_method": "stripe", "payment_method_title": "Credit Card", "set_paid": true, "billing": { "first_name": "John", "last_name": "Doe", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "postcode": "12345", "country": "US", "email": "[email protected]", "phone": "555-1234" }, "shipping": { "first_name": "John", "last_name": "Doe", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "postcode": "12345", "country": "US" }, "line_items": [ { "product_id": 123, "quantity": 2 } ] } ```

#### Update an Order (更新订单)

```bash PUT /woocommerce/wp-json/wc/v3/orders/{id} ```

**示例 - 更新订单状态：**

```bash curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders/456" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"status": "completed"}' ```

#### Delete an Order (删除订单)

```bash DELETE /woocommerce/wp-json/wc/v3/orders/{id} ```

### Order Notes (订单备注)

#### List Order Notes (列出订单备注)

```bash GET /woocommerce/wp-json/wc/v3/orders/{order_id}/notes ```

#### Create Order Note (创建订单备注)

```bash POST /woocommerce/wp-json/wc/v3/orders/{order_id}/notes Content-Type: application/json

{ "note": "Order shipped via FedEx, tracking #12345", "customer_note": true } ```

- `customer_note`：设置为 `true` 以使客户可以看到该备注

#### Get/Delete Order Note (获取/删除订单备注)

```bash GET /woocommerce/wp-json/wc/v3/orders/{order_id}/notes/{id} DELETE /woocommerce/wp-json/wc/v3/orders/{order_id}/notes/{id} ```

### Order Refunds (订单退款)

#### List Refunds (列出退款)

```bash GET /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds ```

#### Create Refund (创建退款)

```bash POST /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds Content-Type: application/json

{ "amount": "25.00", "reason": "Product damaged during shipping", "api_refund": true } ```

- `api_refund`：设置为 `true` 以通过支付网关处理退款

#### Get/Delete Refund (获取/删除退款)

```bash GET /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds/{id} DELETE /woocommerce/wp-json/wc/v3/orders/{order_id}/refunds/{id} ```

---

### Customers (客户)

#### List All Customers (列出所有客户)

```bash GET /woocommerce/wp-json/wc/v3/customers ```

查询参数： - `page` - 当前页码（默认：1） - `per_page` - 每页项目数（默认：10） - `search` - 按名称或电子邮件搜索 - `email` - 按精确电子邮件筛选 - `role` - 按角色筛选：`all`（所有）、`administrator`（管理员）、`customer`（客户）、`shop_manager`（商店经理） - `orderby` - 排序依据：`id`（ID）、`include`（包含）、`name`（名称）、`registered_date`（注册日期） - `order` - 排序顺序：`asc`（升序）、`desc`（降序）

**示例：**

```bash curl -s -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/customers?per_page=25" -H "Authorization: Bearer $MATON_API_KEY" ```

**响应：** ```json [ { "id": 12, "email": "[email protected]", "first_name": "John", "last_name": "Doe", "username": "johndoe", "billing": { "first_name": "John", "last_name": "Doe", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "postcode": "12345", "country": "US", "email": "[email protected]", "phone": "555-1234" }, "shipping": { "first_name": "John", "last_name": "Doe", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "postcode": "12345", "country": "US" } } ] ```

#### Get a Customer (获取单个客户)

```bash GET /woocommerce/wp-json/wc/v3/customers/{id} ```

#### Create a Customer (创建客户)

```bash POST /woocommerce/wp-json/wc/v3/customers Content-Type: application/json

{ "email": "[email protected]", "first_name": "Jane", "last_name": "Smith", "username": "janesmith", "password": "secure_password", "billing": { "first_name": "Jane", "last_name": "Smith", "address_1": "456 Oak Ave", "city": "Springfield", "state": "IL", "postcode": "62701", "country": "US", "email": "[email protected]", "phone": "555-5678" } } ```

#### Update a Customer (更新客户)

```bash PUT /woocommerce/wp-json/wc/v3/customers/{id} ```

#### Delete a Customer (删除客户)

```bash DELETE /woocommerce/wp-json/wc/v3/customers/{id} ```

### Customer Downloads (客户下载)

```bash GET /woocommerce/wp-json/wc/v3/customers/{customer_id}/downloads ```

返回客户有权访问的可下载产品。

---

### Coupons (优惠券)

#### List All Coupons (列出所有优惠券)

```bash GET /woocommerce/wp-json/wc/v3/coupons ```

查询参数： - `page` - 当前页码（默认：1） - `per_page` - 每页项目数（默认：10） - `search` - 搜索优惠券 - `code` - 按优惠券代码筛选

#### Get a Coupon (获取单个优惠券)

```bash GET /woocommerce/wp-json/wc/v3/coupons/{id} ```

#### Create a Coupon (创建优惠券)

```bash POST /woocommerce/wp-json/wc/v3/coupons Content-Type: application/json

{ "code": "SUMMER2024", "discount_type": "percent", "amount": "15", "description": "Summer promotion - 15% off", "date_expires": "2024-08-31T23:59:59", "individual_use": true, "usage_limit": 100, "usage_limit_per_user": 1, "minimum_amount": "50.00", "maximum_amount": "500.00", "free_shipping": false, "exclude_sale_items": true } ```

**折扣类型：** - `percent` - 百分比折扣 - `fixed_cart` - 购物车固定金额减免 - `fixed_product` - 单个产品固定金额减免

**优惠券属性：** - `code` - 优惠券代码（必填） - `amount` - 折扣金额 - `discount_type` - 折扣类型 - `description` - 优惠券描述 - `date_expires` - 到期日期 (ISO8601) - `individual_use` - 不能与其他优惠券结合使用 - `product_ids` - 优惠券适用的产品 ID 数组 - `excluded_product_ids` - 排除的产品 ID 数组 - `usage_limit` - 优惠券可使用的总次数 - `usage_limit_per_user` - 每位客户的使用限制 - `limit_usage_to_x_items` - 折扣适用的最大商品数 - `free_shipping` - 启用免费配送 - `product_categories` - 分类 ID 数组 - `excluded_product_categories` - 排除的分类 ID 数组 - `exclude_sale_items` - 折扣排除特惠商品 - `minimum_amount` - 所需的最低购物车总额 - `maximum_amount` - 允许的最高购物车总额 - `email_restrictions` - 允许的电子邮件地址数组

#### Update a Coupon (更新优惠券)

```bash PUT /woocommerce/wp-json/wc/v3/coupons/{id} ```

#### Delete a Coupon (删除优惠券)

```bash DELETE /woocommerce/wp-json/wc/v3/coupons/{id} ```

---

### Taxes (税收)

#### Tax Rates (税率)

```bash GET /woocommerce/wp-json/wc/v3/taxes POST /woocommerce/wp-json/wc/v3/taxes GET /woocommerce/wp-json/wc/v3/taxes/{id} PUT /woocommerce/wp-json/wc/v3/taxes/{id} DELETE /woocommerce/wp-json/wc/v3/taxes/{id} POST /woocommerce/wp-json/wc/v3/taxes/batch ```

**创建税率示例：**

```bash curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/taxes" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"country": "US", "state": "CA", "rate": "7.25", "name": "CA State Tax", "shipping": true}' ```

#### Tax Classes (税级)

```bash GET /woocommerce/wp-json/wc/v3/taxes/classes POST /woocommerce/wp-json/wc/v3/taxes/classes DELETE /woocommerce/wp-json/wc/v3/taxes/classes/{slug} ```

---

### Shipping (配送)

#### Shipping Zones (配送区域)

```bash GET /woocommerce/wp-json/wc/v3/shipping/zones POST /woocommerce/wp-json/wc/v3/shipping/zones GET /woocommerce/wp-json/wc/v3/shipping/zones/{id} PUT /woocommerce/wp-json/wc/v3/shipping/zones/{id} DELETE /woocommerce/wp-json/wc/v3/shipping/zones/{id} ```

**创建配送区域示例：**

```bash curl -s -X POST "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/shipping/zones" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"name": "US West Coast", "order": 1}' ```

#### Shipping Zone Locations (配送区域位置)

```bash GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/locations PUT /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/locations ```

**更新区域位置示例：**

```bash curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/shipping/zones/1/locations" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '[{"code": "US:CA", "type": "state"}, {"code": "US:OR", "type": "state"}, {"code": "US:WA", "type": "state"}]' ```

#### Shipping Zone Methods (配送区域方式)

```bash GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods POST /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods GET /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id} PUT /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id} DELETE /woocommerce/wp-json/wc/v3/shipping/zones/{zone_id}/methods/{id} ```

#### Shipping Methods (Global) (配送方式 - 全局)

```bash GET /woocommerce/wp-json/wc/v3/shipping_methods GET /woocommerce/wp-json/wc/v3/shipping_methods/{id} ```

---

### Payment Gateways (支付网关)

```bash GET /woocommerce/wp-json/wc/v3/payment_gateways GET /woocommerce/wp-json/wc/v3/payment_gateways/{id} PUT /woocommerce/wp-json/wc/v3/payment_gateways/{id} ```

**示例 - 启用支付网关：**

```bash curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/payment_gateways/stripe" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"enabled": true}' ```

---

### Settings (设置)

#### List Settings Groups (列出设置组)

```bash GET /woocommerce/wp-json/wc/v3/settings ```

#### List Settings in a Group (列出组中的设置)

```bash GET /woocommerce/wp-json/wc/v3/settings/{group} ```

常用组：`general`（常规）、`products`（产品）、`tax`（税收）、`shipping`（配送）、`checkout`（结账）、`account`（账户）、`email`（电子邮件）

#### Get/Update a Setting (获取/更新设置)

```bash GET /woocommerce/wp-json/wc/v3/settings/{group}/{id} PUT /woocommerce/wp-json/wc/v3/settings/{group}/{id} ```

**示例 - 更新商店地址：**

```bash curl -s -X PUT "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/settings/general/woocommerce_store_address" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"value": "123 Commerce St"}' ```

#### Batch Update Settings (批量更新设置)

```bash POST /woocommerce/wp-json/wc/v3/settings/{group}/batch ```

---

### Webhooks (Web 钩子)

#### List All Webhooks (列出所有 Webhooks)

```bash GET /woocommerce/wp-json/wc/v3/webhooks ```

#### Create a Webhook (创建 Webhook)

```bash POST /woocommerce/wp-json/wc/v3/webhooks Content-Type: application/json

{ "name": "Order Created", "topic": "order.created", "delivery_url": "https://example.com/webhooks/woocommerce", "status": "active" } ```

**Webhook 主题：** - `order.created`, `order.updated`, `order.deleted`, `order.restored` - `product.created`, `product.updated`, `product.deleted`, `product.restored` - `customer.created`, `customer.updated`, `customer.deleted` - `coupon.created`, `coupon.updated`, `coupon.deleted`, `coupon.restored`

#### Get/Update/Delete Webhook (获取/更新/删除 Webhook)

```bash GET /woocommerce/wp-json/wc/v3/webhooks/{id} PUT /woocommerce/wp-json/wc/v3/webhooks/{id} DELETE /woocommerce/wp-json/wc/v3/webhooks/{id} ```

---

### Reports (报告)

#### List Available Reports (列出可用报告)

```bash GET /woocommerce/wp-json/wc/v3/reports ```

#### Sales Report (销售报告)

```bash GET /woocommerce/wp-json/wc/v3/reports/sales ```

查询参数： - `period` - 报告周期：`week`（本周）、`month`（本月）、`last_month`（上月）、`year`（今年） - `date_min` / `date_max` - 自定义日期范围

#### Top Sellers Report (热销商品报告)

```bash GET /woocommerce/wp-json/wc/v3/reports/top_sellers ```

#### Coupons Totals (优惠券总计)

```bash GET /woocommerce/wp-json/wc/v3/reports/coupons/totals ```

#### Customers Totals (客户总计)

```bash GET /woocommerce/wp-json/wc/v3/reports/customers/totals ```

#### Orders Totals (订单总计)

```bash GET /woocommerce/wp-json/wc/v3/reports/orders/totals ```

#### Products Totals (产品总计)

```bash GET /woocommerce/wp-json/wc/v3/reports/products/totals ```

#### Reviews Totals (评论总计)

```bash GET /woocommerce/wp-json/wc/v3/reports/reviews/totals ```

---

### Data (数据)

#### List All Data Endpoints (列出所有数据端点)

```bash GET /woocommerce/wp-json/wc/v3/data ```

#### Continents (洲)

```bash GET /woocommerce/wp-json/wc/v3/data/continents GET /woocommerce/wp-json/wc/v3/data/continents/{code} ```

#### Countries (国家)

```bash GET /woocommerce/wp-json/wc/v3/data/countries GET /woocommerce/wp-json/wc/v3/data/countries/{code} ```

#### Currencies (货币)

```bash GET /woocommerce/wp-json/wc/v3/data/currencies GET /woocommerce/wp-json/wc/v3/data/currencies/{code} GET /woocommerce/wp-json/wc/v3/data/currencies/current ```

---

### System Status (系统状态)

```bash GET /woocommerce/wp-json/wc/v3/system_status GET /woocommerce/wp-json/wc/v3/system_status/tools POST /woocommerce/wp-json/wc/v3/system_status/tools/{id} ```

---

## Batch Operations (批量操作)

大多数资源支持批量创建、更新和删除多个项目：

```bash POST /woocommerce/wp-json/wc/v3/{resource}/batch Content-Type: application/json

{ "create": [ {"name": "New Product 1", "regular_price": "19.99"}, {"name": "New Product 2", "regular_price": "29.99"} ], "update": [ {"id": 123, "regular_price": "24.99"} ], "delete": [456, 789] } ```

**响应：** ```json { "create": [...], "update": [...], "delete": [...] } ```

## Pagination (分页)

WooCommerce 使用基于页码的分页，并在响应头中提供信息：

**查询参数：** - `page` - 页码（默认：1） - `per_page` - 每页项目数（默认：10，最大：100） - `offset` - 起始偏移量

**响应头：** - `X-WP-Total` - 项目总数 - `X-WP-TotalPages` - 总页数 - `Link` - 包含 `next`（下一页）、`prev`（上一页）、`first`（第一页）、`last`（最后一页）的分页链接

**示例：**

```bash curl -s -I -X GET "https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products?page=2&per_page=25" -H "Authorization: Bearer $MATON_API_KEY" ```

## Code Examples (代码示例)

### JavaScript

```javascript const response = await fetch( 'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders?status=processing', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const orders = await response.json(); ```

### Python

```python import os import requests

response = requests.get( 'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'per_page': 50, 'status': 'publish'} ) products = response.json() ```

### 创建包含订单项目的订单

```python import os import requests

order_data = { "payment_method": "stripe", "set_paid": True, "billing": { "first_name": "John", "last_name": "Doe", "email": "[email protected]", "address_1": "123 Main St", "city": "Anytown", "state": "CA", "postcode": "12345", "country": "US" }, "line_items": [ {"product_id": 123, "quantity": 2}, {"product_id": 456, "quantity": 1} ] }

response = requests.post( 'https://gateway.maton.ai/woocommerce/wp-json/wc/v3/orders', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json=order_data ) order = response.json() ```

## 注意

- 所有货币金额均以字符串形式返回，且保留两位小数 - 日期采用 ISO8601 格式：`YYYY-MM-DDTHH:MM:SS` - 资源 ID 为整数 - API 要求在 WordPress 中启用“美观固定链接” - 使用 `context=edit` 参数以获取额外的可写字段 - 重要：使用 curl 命令时，如果 URL 包含括号（如 `fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开。进行管道操作时，您可能会遇到“Invalid API key”（无效的 API 密钥）错误。

## 错误处理

| 状态 | 含义 | |--------|---------| | 400 | 请求错误或数据无效 | | 401 | 认证无效或缺失 | | 403 | 禁止访问 - 权限不足 | | 404 | 未找到资源 | | 500 | 服务器内部错误 |

**错误响应格式：** ```json { "code": "woocommerce_rest_invalid_id", "message": "Invalid ID.", "data": { "status": 404 } } ```

### 故障排除：API 密钥问题

1. 检查是否已设置 `MATON_API_KEY` 环境变量：

```bash echo $MATON_API_KEY ```

2. 通过列出连接来验证 API 密钥是否有效：

```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```

### 故障排除：应用名称无效

1. 确保您的 URL 路径以 `woocommerce` 开头。例如：

- 正确：`https://gateway.maton.ai/woocommerce/wp-json/wc/v3/products` - 错误：`https://gateway.maton.ai/wp-json/wc/v3/products`

## 资源

### 通用 - [WooCommerce REST API 文档](https://woocommerce.github.io/woocommerce-rest-api-docs/) - [API 认证指南](https://woocommerce.github.io/woocommerce-rest-api-docs/#authentication) - [WooCommerce 开发者资源](https://developer.woocommerce.com/)

### 产品 - [产品](https://woocommerce.github.io/woocommerce-rest-api-docs/#products) - [产品变体](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-variations) - [产品属性](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-attributes) - [产品属性项](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-attribute-terms) - [产品分类](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-categories) - [产品标签](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-tags) - [产品配送分类](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-shipping-classes) - [产品评论](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-reviews)

### 订单 - [订单](https://woocommerce.github.io/woocommerce-rest-api-docs/#orders) - [订单备注](https://woocommerce.github.io/woocommerce-rest-api-docs/#order-notes) - [退款](https://woocommerce.github.io/woocommerce-rest-api-docs/#refunds)

### 客户 - [客户](https://woocommerce.github.io/woocommerce-rest-api-docs/#customers)

### 优惠券 - [优惠券](https://woocommerce.github.io/woocommerce-rest-api-docs/#coupons)

### 税务 - [税率](https://woocommerce.github.io/woocommerce-rest-api-docs/#tax-rates) - [税务类别](https://woocommerce.github.io/woocommerce-rest-api-docs/#tax-classes)

### 配送 - [配送区域](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zones) - [配送区域位置](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zone-locations) - [配送区域方式](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-zone-methods) - [配送方式](https://woocommerce.github.io/woocommerce-rest-api-docs/#shipping-methods)

### 支付与设置 - [支付网关](https://woocommerce.github.io/woocommerce-rest-api-docs/#payment-gateways) - [设置](https://woocommerce.github.io/woocommerce-rest-api-docs/#settings) - [设置选项](https://woocommerce.github.io/woocommerce-rest-api-docs/#setting-options)

### Webhooks - [Webhooks](https://woocommerce.github.io/woocommerce-rest-api-docs/#webhooks)

### 报表 - [报表](https://woocommerce.github.io/woocommerce-rest-api-docs/#reports) - [销售报表](https://woocommerce.github.io/woocommerce-rest-api-docs/#sales-reports) - [热销商品报表](https://woocommerce.github.io/woocommerce-rest-api-docs/#top-sellers-report) - [优惠券总计](https://woocommerce.github.io/woocommerce-rest-api-docs/#coupons-totals) - [客户总计](https://woocommerce.github.io/woocommerce-rest-api-docs/#customers-totals) - [订单总计](https://woocommerce.github.io/woocommerce-rest-api-docs/#orders-totals) - [产品总计](https://woocommerce.github.io/woocommerce-rest-api-docs/#products-totals) - [评论总计](https://woocommerce.github.io/woocommerce-rest-api-docs/#reviews-totals)

### 数据 - [数据](https://woocommerce.github.io/woocommerce-rest-api-docs/#data) - [洲](https://woocommerce.github.io/woocommerce-rest-api-docs/#continents) - [国家](https://woocommerce.github.io/woocommerce-rest-api-docs/#countries) - [货币](https://woocommerce.github.io/woocommerce-rest-api-docs/#currencies)

### 系统 - [系统状态](https://woocommerce.github.io/woocommerce-rest-api-docs/#system-status) - [系统状态工具](https://woocommerce.github.io/woocommerce-rest-api-docs/#system-status-tools) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])

返回

更多产品

Github

Git 与 GitHub

使用 `gh` CLI 与 GitHub 交互。使用 `gh issue`、`gh pr`、`gh run` 和 `gh api` 处理 issue、PR、CI 运行和高级查询。

21.4K

API Gateway

Git 与 GitHub

通过 OAuth 仅需几次点击即可与第三方 API（Google Workspace、Outlook、GitHub、Stripe、HubSpot 等）集成。当用户希望...时使用此技能

11.6K

Xero

Git 与 GitHub

使用托管 OAuth 集成 Xero API。管理联系人、发票、付款、帐户并运行财务报告。当用户想要交互时使用此技能

7.8K