etsy

用途该技能封装 Etsy Open API v3，用于店铺（shop）与商品刊登（listing）管理。当用户提及 Etsy、店铺商品、Etsy 订单、商品刊登或 Etsy 卖家时适用。

主要能力

Ping / 健康检查：验证 API 连通性与凭证有效性。
获取店铺：通过店铺 ID 获取店铺信息，返回包含店铺名称、URL、商品数量与卖家详情。
按名称查找店铺：通过 shop_name 搜索店铺。
列出店铺活跃商品：返回商品 ID、标题、价格、数量与 URL。
获取单个商品详情。
搜索所有店铺的活跃商品，支持关键词、分页与排序参数。
获取商品图片。
获取商品库存。

使用方式认证：所有请求需在请求头中传入 API 凭证：x-api-key: $ETSY_TOKEN。ETSY_TOKEN 必须设置为 <keystring>:<shared_secret> 格式，即两个值用冒号连接，从 Etsy 开发者门户的 Your Apps 获取。

基础 URL：https://openapi.etsy.com

关键端点示例：

Ping：curl -s "https://openapi.etsy.com/v3/application/openapi-ping" --header "x-api-key: $ETSY_TOKEN"
按 ID 获取店铺：curl -s "https://openapi.etsy.com/v3/application/shops/<your-shop-id>" --header "x-api-key: $ETSY_TOKEN"
按名称查找店铺：curl -s "https://openapi.etsy.com/v3/application/shops?shop_name=<your-shop-name>&limit=10" --header "x-api-key: $ETSY_TOKEN"
列出活跃商品：curl -s "https://openapi.etsy.com/v3/application/shops/<your-shop-id>/listings/active?limit=25" --header "x-api-key: $ETSY_TOKEN"
获取单个商品：curl -s "https://openapi.etsy.com/v3/application/listings/<your-listing-id>" --header "x-api-key: $ETSY_TOKEN"
搜索活跃商品：curl -s "https://openapi.etsy.com/v3/application/listings/active?keywords=<your-search-term>&limit=25&sort_on=score" --header "x-api-key: $ETSY_TOKEN"，支持参数 keywords、limit（最大 100）、offset、sort_on（score、created、price、updated）、sort_order（asc 或 desc）、min_price / max_price。
获取商品图片：curl -s "https://openapi.etsy.com/v3/application/listings/<your-listing-id>/images" --header "x-api-key: $ETSY_TOKEN"
获取商品库存：curl -s "https://openapi.etsy.com/v3/application/listings/<your-listing-id>/inventory" --header "x-api-key: $ETSY_TOKEN"

故障排查若请求失败，可运行 zero doctor check-connector --env-name ETSY_TOKEN 或 zero doctor check-connector --url https://openapi.etsy.com/v3/application/openapi-ping --method GET。

环境变量 ETSY_TOKEN：Etsy API 凭证，格式为 keystring:shared_secret。

限制

速率限制：Etsy 按 API key 强制执行速率限制，应避免密集轮询循环。
收据 / 订单：交易与收据端点需要 OAuth 2.0 授权，不能仅用 API key 认证访问。
分页：对大数据集使用 limit（最大 100）与 offset 参数。
商品状态：/listings/active 用于公开可见商品；其他状态（草稿、已过期）需要 OAuth。

技能介绍