linkfox-shopee-store-auth

Shopee ショップの認証と管理

Shopee Open Platform の OAuth 認証、認証済みショップ一覧、認証状態の取得。下流業務の前提条件です（/shopee/developerProxy 経由でオープン API を呼び出します）。

Shopee の ERP と広告（AD）では、アプリとトークンが異なるため、機能ごとに分けて認証する必要があります。

基本概念

• 2 つのアプリ：appType=erp（商品／注文／物流など。デフォルト）と appType=ad（サイト内広告）はそれぞれ独立しています。同じショップに両方の認証を設定できます
• 認証フロー：URL を生成 → ユーザーがブラウザーで認証 → Shopee がトークンを送信 → システムが state に基づいてデータベースに保存
• ショップ識別子：shopId と merchantId のどちらかで特定できます。認証済みかどうかを判断するには、shopId/merchantId + appType の両方を照合する必要があります
• shopName の入力を推奨：authorize_url.py を呼び出す前に、識別しやすいショップ名をユーザーに確認することを推奨します（API では任意）
• 認証 URL の有効期間は 1 時間：認証のたびに authorize_url.py を再度呼び出してください。古い URL をキャッシュしないでください
• 下流のショップ選択：業務スキルは developerProxy に shopId／merchantId + path だけを渡します。accessToken は渡さず、proxy に appType も渡さないでください（サーバーが path に基づいて自動的にルーティングします：api/v2/ads/** → AD、それ以外の api/v2/** → ERP）
• accessToken の有効期間は約 4 時間（expireIn は通常 14400）です。期限切れになった場合は、該当する appType で再認証が必要です

Shopee の認証ルーティング

• 商品、注文、物流などの ERP 認証には appType=erp を使用します。
• Shopee Ads の認証には appType=ad を使用します。
• appType がない、または空の場合は erp として扱います。
• ショップの識別情報と appType の両方で認証状態を確認してください。同じショップに ERP と AD の別々のレコードが存在する場合があります。
• ユーザーが両方の機能を必要とする場合は、新しい認証 URL を 2 つ取得し、両方の認証を完了する必要があることを説明してください。
• 認証 URL の有効期間は 1 時間です。認証を試みるたびに新しい URL を取得してください。

developerProxy の呼び出し時には、Shopee API の path と shopId または merchantId を渡してください。appType やアクセストークンは渡さないでください。サービスは api/v2/ads/** を AD アプリ経由でルーティングし、それ以外のすべての api/v2/** パスを ERP アプリ経由でルーティングします。

利用可能なスクリプト

スクリプト	用途
authorize_url.py	認証 URL を生成します（shopName／region／appType は任意）
authorized_stores.py	認証済みショップを一覧表示します（appType を含みます。同じショップが 2 件表示される場合があります）
store_tokens.py	指定アプリの認証／トークンの状態を確認します（下流のトークン取得元ではありません。appType を指定して区別する必要があります）

パラメーター、レスポンスフィールド、エラーコードについては references/api.md を参照してください。

呼び出し方法

• API エンドポイント：POST /shopee/{authorizeUrl|storeTokens|authorizedStores}（全パラメーター／レスポンス／エラーコードについては references/api.md を参照してください）
• Python スクリプト：python scripts/<スクリプト名>.py '<JSON パラメーター>' [--inline]（利用可能なスクリプトは上記を参照してください）
• コストに関する制約：このツールは計算リソースを消費します。失敗した場合や結果が空の場合に、自動で連続して試行しないでください。検索を続ける必要がある場合は、追加のリソースが消費されることを事前にユーザーに説明してください。

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリにあたります。<session> は環境変数 SESSION_ID から取得され、ユーザーのタスクごとに自動でまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、一般的な件数、最大のリストフィールドの長さと先頭 3 件のサンプル）
• --inline を付けると、ファイルにも保存したうえで stdout に全内容を強制出力します

データの読み取りに関する推奨事項：まず要約を見て十分かどうかを判断してください。具体的なフィールドが必要な場合は、保存された JSON ファイルから jq または ConvertFrom-Json を使って必要な項目だけを抽出し、JSON 全体がコンテキストに入るのを避けてください。

認証と計算リソースに関する問題の解決

以下の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状態

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY と LINKFOXAGENT_API_KEY のどちらも設定されていません。
• 401 または 402 ステータスコードが返された
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「計算リソースの残高不足／課金不足／残高不足／quota exceeded／insufficient balance／プランの有効期限切れ／チャージが必要／チャージしてください」、または同様の意味を含む場合。

対応地域

cn（中国向け越境。デフォルト）／global（グローバル認証ページ）／br（ブラジル）。デフォルトは cn です。

利用シナリオ

1. 新しいショップを認証する（ERP、デフォルト）

1. ユーザーに shopName を確認することを推奨します（後で識別しやすくするため。API では任意です）
2. region を確認します（デフォルトは cn。グローバルサイトは global、ブラジルは br）
3. authorize_url.py を呼び出し、appType=erp を渡します（または省略します。サーバーのデフォルトは erp です）→ ユーザーにブラウザーで開いてもらいます（セキュリティ上の警告：ショップの安全を確保するため、必ずそのショップの日常的な運用に使用する安全なネットワーク環境でこのリンクを開いてください。紫鳥ブラウザーなどのアカウント関連付け防止に特化したブラウザーの使用を強く推奨します。見知らぬネットワークや公共ネットワークで操作しないでください。）
4. 認証完了後、システムが自動的にトークンを保存します。ブラウザーは成功ページまたは失敗ページに移動します
5. authorized_stores.py を呼び出し、appType=erp（または空。過去の記録は erp として扱います）のレコードが存在することを確認します

2. 広告アプリを認証する（AD）

1. authorized_stores.py を呼び出し、対象ショップに appType=ad がすでにあるか確認します
2. 未認証の場合は authorize_url.py を呼び出して appType=ad を渡し、これが ERP とは別の広告アプリの認証であることを明確にユーザーに伝えます
3. 認証完了後、再度 appType=ad を確認します
4. ERP の認証を広告の認証の代わりに使用することは禁止されています

3. ERP と広告の両方が必要な場合

1. appType=erp と appType=ad をそれぞれ確認します
2. 未認証のアプリに対してのみ認証 URL を生成します。両方とも未認証の場合は、用途を明記した URL を2 つ生成します
3. それぞれの URL を開いて 2 回認証を完了する必要があることをユーザーに伝えます。一方の認証がもう一方の機能を上書きすることはありません

4. 認証済みショップを一覧表示する

authorized_stores.py を呼び出し、shopName / shopId / merchantId / region / **appType** を表示します。同じショップに ERP と AD の 2 件が表示される場合があります。

5. 下流向けに店舗選択情報を準備する（高頻度）

ユーザーは自然言語（「私のShopee店舗」「67890の店舗」）だけを指定します。長いトークンをユーザーに報告させないでください。

ユーザーのコンテキスト	エージェントのアクション
1店舗のみ認可済み（かつ対象機能が認可済み）	その店舗の shopId（または merchantId）を直接取得します。質問は不要です
2店舗以上が認可済み＋店舗名のみ指定	shopName に基づいてユーザーに確認します
shopName または shopId を指定	直接特定します
shopId / merchantId を明示的に指定	そのまま使用します
店舗はリストに存在するが、対象の appType が不足	機能に応じた認可を開始します。業務 API は呼び出さないでください

サイレント原則：特定に成功した場合は、店舗識別子とアプリケーションの種類のみを確認し、ユーザーにトークンを求めないでください。

推奨フロー：authorized_stores.py で shopId + appType に基づき認可済みであることを確認 → 下流のスキルから shopId（または merchantId）を指定して POST /shopee/developerProxy を直接実行し、サーバー側で path に基づいて対応するアプリケーショントークンを解決します。

store_tokens.py は認可／トークンの状態確認にのみ使用してください（appType の指定が必要です）。proxy 呼び出しの前に accessToken を取得しないでください。

呼び出し原則

• 認可の前に shopName、region、appType を確認することを推奨します
• storeTokens のレスポンスに raw accessToken が含まれると想定しないでください。状態と有効期限のメタデータを表示すれば十分です
• 認可に失敗した場合は、エラーコードに基づいて原因を説明してください。独断で再試行しないでください
• トークンの有効期限が切れた場合は、対応する appType の認可フローを再度実行する必要があります
• 履歴の空の app_type は ERP とみなします。AD ではありません

よくある問題

認可完了後に店舗が見つからない

原因：トークンのプッシュコールバック（/shopee/oauth/tokenCallback）が正常に保存されなかったか、state が一致していません。
解決方法：サーバーログを確認し、authorize_url.py を再度実行して（期限切れの URL は再利用しないでください）、認可を完了します。

トークンの確認／業務呼び出しで 1004 が返される

原因：shopId / merchantId が間違っているか、対象のアプリケーションが認可されていません（例：ERP のみで AD がない）。
解決方法：まず authorized_stores.py を実行して shopId + appType を確認します。不足している場合は、機能に応じて再認可します。

店舗は認可済みだが、広告 API が失敗する

原因：ERP の記録があること ≠ AD の記録があることです。広告には ERP Token を使用できません。
解決方法：appType=ad の認可を開始してから、linkfox-shopee-store-ads を呼び出します。

対象外

• Shopee の注文照会と処理 → linkfox-shopee-store-orders
• Shopee の店舗情報と設定 → linkfox-shopee-store-shop
• Shopee 店舗の商品 listing → linkfox-shopee-store-product
• Shopee 越境グローバル商品 GlobalProduct → linkfox-shopee-store-global-product
• Shopee 越境マーチャント情報 Merchant → linkfox-shopee-store-merchant
• Shopee の物流・発送 Logistics → linkfox-shopee-store-logistics
• Shopee の返品・返金 Returns → linkfox-shopee-store-returns
• Shopee のサイト内広告 Ads → linkfox-shopee-store-ads（業務呼び出し。認可には引き続きこのスキルの appType=ad を使用）
• Shopee の支払い・精算 Payment → linkfox-shopee-store-payment
• Shopee アフィリエイトマーケティング AMS → linkfox-shopee-store-ams
• Shopee 店舗動画 Video → linkfox-shopee-store-video
• Shopee メディアアップロード MediaSpace → linkfox-shopee-store-media-space
• Shopee メディアアップロード Media → linkfox-shopee-store-media（api/v2/media/...、module=130）
• Shopee 初期区間物流 FirstMile → linkfox-shopee-store-first-mile
• Shopee 割引プロモーション Discount → linkfox-shopee-store-discount
• Shopee セット割 Bundle Deal → linkfox-shopee-store-bundle-deal
• Shopee 追加購入割引 Add-On Deal → linkfox-shopee-store-add-on-deal
• Shopee 店舗クーポン Voucher → linkfox-shopee-store-voucher
• Shopee 店舗フラッシュセール Shop Flash Sale → linkfox-shopee-store-shop-flash-sale
• Shopee フォロー特典 Follow Prize → linkfox-shopee-store-follow-prize
• Shopee おすすめ商品 Top Picks → linkfox-shopee-store-top-picks
• Shopee 店舗カテゴリ Shop Category → linkfox-shopee-store-shop-category
• Shopee アカウント健全性 Account Health → linkfox-shopee-store-account-health
• Shopee Public 共通モジュール → linkfox-shopee-store-public（v2.public.* の基盤となる OAuth / Partner クエリ）
• Shopee Push プッシュ機能 → linkfox-shopee-store-push
• Shopee SBS 倉庫サービス → linkfox-shopee-store-sbs
• Shopee FBS ブラジル倉庫 → linkfox-shopee-store-fbs
• Shopee ライブ配信 Livestream → linkfox-shopee-store-livestream
• Shopee の商品リサーチ（友鹰） → linkfox-youying-shopee-product-search
• 商品 listing 管理 → 専用の product スキルまたは developerProxy の商品 API

コンピューティング消費ルール

コンピューティングを消費しません。

フィードバック：

次のいずれかに該当する場合は、フィードバックを自動検出し、Feedback API 経由で報告してください。

1. このスキルで説明されている機能や目的が、実際の動作と一致しない
2. スキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルへの不満または称賛を表明する
4. 改善できると思われることがある

references/api.md の指定に従って Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境 EC スキルをさらにご覧になるには、LinkFox Skills にアクセスしてください。