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. 04Webhook の作成と管理
  5. 05リクエストと OAuth 用スクリプト
  6. 06Webhook 署名の検証

活用シーン

  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 ショップのリソースを読み取る、または変更する必要がある場合に、このスキルを使用します。対象には次のものが含まれます。

  • 出品：下書きの作成、出品メタデータの更新、画像やファイルのアップロード、動画の管理、在庫や販売内容の更新
  • ショップ：ショップ設定、ショップセクション、配送プロファイル、処理プロファイル、返品ポリシーの取得や更新
  • レシート／注文：レシートや取引の取得、購入後のワークフロー
  • タクソノミー：販売者／購入者向けのタクソノミーノードとプロパティ
  • Webhook：エンドポイントの作成／ローテーション、イベントのサブスクライブ、署名の検証

このスキルパッケージには、適切なリクエストをレート制限に配慮して行うためのリファレンスドキュメントとスクリプトが含まれています。

認証モデル（重要）

Etsy では、次のものを使用します。

  • すべてのリクエストでAPI キーヘッダー
  • スコープ付き／非公開エンドポイントでOAuth 2.0 ユーザートークン（認可コード＋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（1 秒あたりのクエリ数）
  • QPD（1 日あたりのクエリ数）。直近 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 テストポリシー（下書きの出品、テスト価格など）に従ってください。references/11_terms_and_policies.md を参照してください。

安全性とコンプライアンス

  • シークレット（共有シークレット、アクセストークン、リフレッシュトークン）を表示またはログに記録しないでください。
  • テスト中に「実際の」出品や注文を作成しないようにし、Etsy のテストポリシーのガイダンスに従ってください。
  • エンドポイントのパラメーターが不明な場合は、OpenAPI リファレンスサイトまたは OpenAPI 仕様を確認してください。

コメント

Markdown 対応