mcpField
E
etsy-api

etsy-api

github.com/j-dturner其他679 次安装40 周前更新
代码仓库

关于 etsy-api

etsy-api 是通过 Etsy Open API v3 读取和修改 Etsy 店铺资源的技能，附带参考文档和脚本，支持身份验证、限流请求、OAuth 设置及 Webhook 验签。

主要功能

  1. 01管理商品、库存和媒体
  2. 02读取和更新店铺设置
  3. 03访问收据和分类数据
  4. 04创建和管理 Webhook
  5. 05使用脚本发送请求并处理 OAuth
  6. 06验证 Webhook 签名

适用场景

  1. 01更新商品详情或库存
  2. 02获取店铺订单和设置
  3. 03为受限端点配置 OAuth 令牌
  4. 04验证传入的 Webhook 签名

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/j-dturner/etsy-api-skill --skill etsy-api

安装后在 Claude Code 中输入/etsy-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
examples/
list_active_listings.py
references/
00_overview.md
01_skill_standard.md
02_authentication.md
03_request_standards.md
04_rate_limits.md
05_webhooks.md
06_definitions.md
07_openapi_spec.md
08_common_workflows.md
09_error_handling.md
10_scopes.md
11_terms_and_policies.md
references/openapi/
README.md
scripts/
etsy_cli.py
etsy_http.py
fetch_openapi_spec.py
oauth_pkce.py
openapi_search.py
webhook_verify.py

详细介绍

Etsy Open API v3 技能

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

  • Listings：创建草稿、更新 listing 元数据、上传图片/文件、管理视频、更新库存/商品选项
  • Shop：获取/更新店铺设置、店铺分区、配送资料、处理资料、退货政策
  • Receipts/orders：获取收据和交易记录、购买后工作流
  • Taxonomy：卖家/买家分类节点及属性
  • Webhooks：创建/轮换端点、订阅事件、验证签名

此技能包包含参考文档和脚本，可帮助你正确发起请求并考虑速率限制。

身份验证模型（重要）

Etsy 使用：

  • 所有请求都需携带 API 密钥标头
  • 对于有作用域的/私有端点，需使用 OAuth 2.0 用户令牌（Authorization Code + PKCE）
必需的标头

所有请求都必须包含：

  • 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

速率限制（必须遵守）

Etsy 执行按应用的速率限制：

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

收到 HTTP 429 时，请遵循 retry-after 标头的指示并使用指数退避。

请参阅：

  • references/04_rate_limits.md

可运行的脚本（code_execution）

所有脚本都位于 skills/etsy-api/scripts/ 下。

1) 安全地发起请求

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

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 辅助工具（PKCE + 令牌交换）

生成 PKCE 验证器/质询值和授权 URL：

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

使用授权码交换令牌：

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

刷新令牌：

python skills/etsy-api/scripts/oauth_pkce.py refresh-token
3) Webhook 验证

在本地验证 webhook 签名：

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

如何有效使用此技能

  1. 编写代码前，优先阅读 references/，了解政策、速率限制和身份验证详情。
  2. 使用 scripts/etsy_cli.py 进行探索性调用并验证请求格式。
  3. 适当缓存响应，以减少 QPS/QPD 用量。
  4. 测试时务必谨慎：遵循 Etsy 的 API 测试政策（草稿 listing、测试价格等）。请参阅 references/11_terms_and_policies.md。

安全与合规

  • 切勿打印或记录机密信息（共享密钥、访问令牌、刷新令牌）。
  • 测试时避免创建“真实”的 listing/订单；遵循 Etsy 测试政策指南。
  • 如果不确定端点的参数，请查阅 OpenAPI 参考网站或 OpenAPI 规范。

评论

支持 Markdown