etsy-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Etsy Open API v3 Skill

Etsy Open API v3 技能

Use this skill when you need to read or modify Etsy shop resources using Etsy Open API v3, including:

Listings: create drafts, update listing metadata, upload images/files, manage videos, update inventory/offerings
Shop: retrieve/update shop settings, shop sections, shipping profiles, processing profiles, return policies
Receipts/orders: retrieve receipts and transactions, post-purchase workflows
Taxonomy: seller/buyer taxonomy nodes and properties
Webhooks: create/rotate endpoints, subscribe to events, verify signatures

This skill package includes reference docs and scripts to make correct, rate-limit-aware requests.

当你需要使用Etsy Open API v3读取或修改Etsy店铺资源时，可以使用本技能，包括：

商品列表：创建草稿、更新商品元数据、上传图片/文件、管理视频、更新库存/产品供应
店铺：获取/更新店铺设置、店铺分类、配送配置文件、处理配置文件、退货政策
收据/订单：获取收据和交易记录、售后流程
分类体系：卖家/买家分类节点及属性
Webhooks：创建/轮换端点、订阅事件、验证签名

本技能包包含参考文档和脚本，可帮助你发起符合要求且支持速率限制感知的请求。

Authentication model (critical)

认证模型（至关重要）

Etsy uses:

API key header on all requests
OAuth 2.0 user tokens (Authorization Code + PKCE) for scoped/private endpoints

Etsy采用以下认证方式：

所有请求均需携带API key请求头
针对需要权限/私有端点，使用OAuth 2.0用户令牌（授权码 + PKCE）

Required headers

必填请求头

All requests must include:

x-api-key: <ETSY_KEYSTRING>:<ETSY_SHARED_SECRET>

Scoped endpoints additionally require:

Authorization: Bearer <ETSY_OAUTH_USER_ID>.<ETSY_OAUTH_ACCESS_TOKEN>

Note: Etsy’s Bearer token format includes the numeric user id, a dot (
.
), and then the access token.

See:

```
references/02_authentication.md
```
```
references/03_request_standards.md
```

所有请求必须包含：

x-api-key: <ETSY_KEYSTRING>:<ETSY_SHARED_SECRET>

需要权限的端点额外要求：

Authorization: Bearer <ETSY_OAUTH_USER_ID>.<ETSY_OAUTH_ACCESS_TOKEN>

注意：Etsy的Bearer令牌格式包含数字用户ID、一个点（
.
）以及访问令牌。

参考：

```
references/02_authentication.md
```
```
references/03_request_standards.md
```

Rate limits (must follow)

速率限制（必须遵守）

Etsy enforces per-application rate limits:

QPS (queries per second)
QPD (queries per day) using a rolling 24-hour sliding window

When you receive HTTP

, honor the

retry-after

header and use exponential backoff.

See:

```
references/04_rate_limits.md
```

Etsy对每个应用实施速率限制：

QPS（每秒查询次数）
QPD（每日查询次数），采用滚动24小时滑动窗口机制

当收到HTTP

响应时，请遵循

retry-after

请求头的指示，并使用指数退避策略。

参考：

```
references/04_rate_limits.md
```

Scripts you can run (code_execution)

可运行的脚本（code_execution）

All scripts are under

skills/etsy-api/scripts/

所有脚本均位于

skills/etsy-api/scripts/

目录下。

1) Make requests safely

1) 安全发起请求

Use the CLI to perform an arbitrary request with proper headers:

bash

python skills/etsy-api/scripts/etsy_cli.py request GET /v3/application/listings?state=active

You can pass a body for POST/PUT with

--data

(JSON) or

--form

(x-www-form-urlencoded).

使用CLI工具携带正确的请求头执行任意请求：

bash

python skills/etsy-api/scripts/etsy_cli.py request GET /v3/application/listings?state=active

你可以通过

--data

（JSON格式）或

--form

（x-www-form-urlencoded格式）参数为POST/PUT请求传递请求体。

2) OAuth helpers (PKCE + token exchange)

2) OAuth辅助工具（PKCE + 令牌交换）

Generate a PKCE verifier/challenge and an authorization URL:

bash

python skills/etsy-api/scripts/oauth_pkce.py auth-url --scopes "listings_r listings_w shops_r shops_w"

Exchange an authorization code for tokens:

bash

python skills/etsy-api/scripts/oauth_pkce.py exchange-code --code "<AUTH_CODE>"

Refresh a token:

bash

python skills/etsy-api/scripts/oauth_pkce.py refresh-token

生成PKCE验证器/挑战以及授权URL：

bash

python skills/etsy-api/scripts/oauth_pkce.py auth-url --scopes "listings_r listings_w shops_r shops_w"

将授权码交换为令牌：

bash

python skills/etsy-api/scripts/oauth_pkce.py exchange-code --code "<AUTH_CODE>"

刷新令牌：

bash

python skills/etsy-api/scripts/oauth_pkce.py refresh-token

3) Webhook verification

3) Webhook验证

Verify a webhook signature locally:

bash

python skills/etsy-api/scripts/webhook_verify.py verify --secret "$ETSY_WEBHOOK_SIGNING_SECRET" --headers-json headers.json --body-file body.json

本地验证Webhook签名：

bash

python skills/etsy-api/scripts/webhook_verify.py verify --secret "$ETSY_WEBHOOK_SIGNING_SECRET" --headers-json headers.json --body-file body.json

How to use this skill effectively

如何高效使用本技能

Prefer reading references/ for policy, rate limits, and authentication details before coding.
Use
```
scripts/etsy_cli.py
```
for exploratory calls and to validate request shapes.
Cache responses where appropriate to reduce QPS/QPD usage.
Be careful when testing: follow Etsy’s API testing policy (draft listings, test prices, etc.). See
```
references/11_terms_and_policies.md
```
.

在编码前，优先阅读**references/**目录下的文档，了解政策、速率限制和认证细节。
使用
```
scripts/etsy_cli.py
```
进行探索性调用，并验证请求格式。
适当地缓存响应，以减少QPS/QPD的使用量。
测试时需谨慎：遵循Etsy的API测试政策（如使用草稿商品、测试价格等）。参考
```
references/11_terms_and_policies.md
```
。

Safety and compliance

安全与合规

Never print or log secrets (shared secret, access token, refresh token).
Avoid creating “real” listings/orders during testing; follow Etsy testing policy guidance.
If uncertain about an endpoint’s parameters, consult the OpenAPI reference site or the OpenAPI spec.

切勿打印或记录机密信息（共享密钥、访问令牌、刷新令牌）。
测试期间避免创建“真实”的商品列表/订单；遵循Etsy测试政策的指导。
若不确定某个端点的参数，请查阅OpenAPI参考网站或OpenAPI规范。