# Aim / Aim for eBay — API申請と接続の準備

更新日：2026-09-24。申請文は `docs/ebay-api-application.txt`。ブラウザー案内は `/api-setup`。

## 現時点

開発者登録とSandboxキー設定が完了。2026-09-24、公開設定APIでSandboxキー・操作コードの設定済みを確認。利用者から接続テスト完了の報告と、Sandboxセラー検索結果の画面を受領した。認証済み接続レポートの回収と選択商品の抽出確認は未完了。同日、AIMの本番キーセットを作成したが、eBay側では削除通知対応待ちで無効。本番キーのVercel登録・用途承認・本番接続は未完了。既存の保存データからの手動リサーチ・選択商品抽出は利用可能。

今回準備したもの：申請用の英文説明、画面とデータの流れ、Sandbox／本番の接続先・キー分離、操作コードによるAPI利用認証、接続診断、本番の開始条件、設定と検証手順。

運営者は `JIYUJIN Co.,Ltd`（2026-09-24、利用者確認済み）。同日、指定された通知先メールをeBayのAIM Productionキーセットへ登録し、保存成功を確認した。通知先の実値は非公開の運営記録で管理する。所在地（3F）と国も利用者確認済み。同日、eBay開発者の連絡先へ保存し、開発者サポートの有効化完了を確認した。所在地の実値は非公開の運営記録で管理する。申請担当者・通常のeBayアカウントID・公開用プライバシー方針は未確定。推測で補わない。開発者登録とキー作成は完了したが、本番用途の申請送信・追加の規約同意は未実施。

## 手続き

1. [開発者登録](https://developer.ebay.com/join/)とメール認証を行う。通常のeBayアカウントとは別。登録済みの場合はサインインする。
2. Application Keysでアプリ名 `Aim` を入力し、Sandboxの「Create a keyset」からキーを作成。サブタイトルは `Aim for eBay`。App ID = Client ID、Cert ID = Client Secret。今回の実装はDev IDを使わない。
3. 下記のテスト設定を保存して再デプロイ。接続テストを行う。Sandboxにはテスト出品しかないため、日本セラーの件数検証には使わない。
4. 英文資料に事業者情報を補い、実際の月額2,980円の会員向け商用リサーチ用途での適用API・許可範囲を確認する。公式のBuy API本番案内にはEPN／Buy API申請とUX資料の提出、開発者サポートによる審査がある。今回の用途にその経路が適用されるか確認し、回答に沿って申請する。アフィリエイトや購入サービスを実装していると偽って申請しない。
5. 本番キー作成と、削除通知・削除処理・プライバシー方針を完成させる。既存保存データと書き出し機能があるため、通知免除に該当すると決めつけない。
6. 用途承認とデータ取扱条件を実装へ反映後、本番の開始条件を設定し再デプロイ。接続テスト、少量のキーワード検索、セラー選択・商品抽出を確認して利用を開始する。

登録・キー作成：[公式ガイド](https://developer.ebay.com/develop/guides/sell/get-started-with-ebay-apis)。本番アクセス：[Buy API要件](https://developer.ebay.com/api-docs/buy/static/buy-requirements.html)。セラー情報の整理・分析・書き出しは[API利用規約](https://developer.ebay.com/join/api-license-agreement)に照らして必要な書面許可を確認する。接続成功だけで用途承認と判断しない。

## Vercel設定

2026-09-24、本番用の削除通知環境名・受信URLと、受信有効化・用途承認・データ取扱準備の3項目の `false` を保存済み。通知用の秘密値と本番APIキーの登録は未完了で、引き続きSandbox運用中。

eBay専用プロジェクト `free-j-dc / ebay` のEnvironment Variablesへ設定。SLTへ保存しない。実値をGitHub、チャット、画面キャプチャへ出さない。キーと操作コードは機密設定にする。VercelのProduction環境とeBayのProductionは別概念で、本番URL上でも最初はeBay Sandboxへ接続できる。

| 環境変数 | テスト開始時 | 本番開始時 |
|---|---|---|
| `EBAY_ENVIRONMENT` | `sandbox` | `production` |
| `EBAY_SANDBOX_CLIENT_ID` | SandboxのApp ID | テスト用として独立管理 |
| `EBAY_SANDBOX_CLIENT_SECRET` | SandboxのCert ID | テスト用として独立管理 |
| `EBAY_CLIENT_ID` | 未設定で可 | 本番のApp ID |
| `EBAY_CLIENT_SECRET` | 未設定で可 | 本番のCert ID |
| `EBAY_OPERATOR_SECRET` | 32〜256文字。32文字以上のランダム生成コード | 操作担当者だけに渡すコード |
| `EBAY_PRODUCTION_APPROVED` | `false`／未設定 | 対象用途の承認証跡を確認してから `true` |
| `EBAY_DATA_HANDLING_READY` | `false`／未設定 | 下記の運用要件を実装・検証後に `true` |

設定後は再デプロイする。Previewへ本番キーをコピーしない。PreviewテストにはSandboxキーとテスト用コードを個別に設定する。`DATABASE_URL`は既存のeBay専用接続を使用し、今回変更しない。

`EBAY_ENVIRONMENT`未設定時はSandbox。Sandboxキー未設定でも本番キーへフォールバックしない。未知の環境名は拒否する。本番の2つの確認変数は運用者の宣言であり、eBayの審査を代行・自動確認しない。

## 接続と操作の検証

1. `/api-setup` →「設定状況を確認」。GETは設定の有無と操作セッションの状態だけを返し、eBay APIもDBも呼ばない。
2. アプリ操作コードを入力。eBayパスワードやCert IDをここで使わない。4時間有効の署名済み `HttpOnly; Secure; SameSite=Strict` Cookieを使い、コードをlocalStorageへ保存しない。コードを変更すると既存Cookieも無効になる。
3. 「接続テストを実行」。同一Origin・利用認証・開始条件を確認してから、OAuth → Browse検索（最大1出品）→ Taxonomyの順に確認。成功した段階と失敗した段階が分かる。トークン、APIレスポンス本文、秘密値は返さない。
4. Sandbox成功後は、テスト出品に一致するキーワードで日本セラー探索を実行。Sandbox結果はテストデータとして明示される。日本に商品所在地があるテスト出品がなければ0件になり得る。実データの件数不足と混同しない。
5. チェックしたセラーだけの商品が抽出されること、CSV/JSONの取得元がSandboxと分かること、中止・429・エラーで自動継続しないことを確認する。APIの新規出品データを共有DBへ自動蓄積しない。作業状態はタブ内のsessionStorageで最長24時間復元でき、再読込だけでは消えない。期限切れで復元を止めるが、保存領域からの物理削除完了を意味しない。明示保存したセラーは未ログインならlocalStorage、会員なら個人メモへ保存される。

認証方式は[Application access token / client credentials](https://developer.ebay.com/develop/guides/sell/authorization)。ユーザーのeBayログインを求める認可画面やOAuthリダイレクトURLは、この公開出品検索の実装では使用しない。削除通知のコールバックURLとは別の話である。

401はキー・環境・無効化状態、403はAPI権限・スコープ・承認状況、429は利用枠を確認する。再実行は担当者の操作で行う。利用枠を回避するための別キー・環境切替をしない。

## 設定画面の補助機能

- アプリ名「Aim」をコピーできる。
- 「操作コードを作成してコピー」はブラウザーの暗号学的乱数から64文字を生成し、クリップボードだけへ渡す。Vercelには自動登録されない。
- Sandbox・本番のキーの有無を別々に表示し、未設定・入力待ち・接続テスト待ちなど、現在の状態に応じた次の操作を案内する。
- 設定状況と、この画面で実行した接続テストの記録をJSONでダウンロードできる。出力対象を限定し、キー・操作コード・トークン・プロバイダーの生レスポンスを含めない。設定を確認し直すと前回のテスト結果をクリアする。
- APIキーがなくても設定例と申請資料を準備できる。テスト未実行の記録を接続成功として扱わない。

## 本番データ取扱の開始条件（未完了）

削除通知の受信・署名確認・暗号化された永続受付を実装した（詳細は `docs/ebay-deletion-ingress.md`）。初期状態は無効。実データ削除・不変ID照合・書き出しとバックアップの処理は未完了で、通知受信口を完成品として登録しない。`EBAY_DELETION_INGRESS_ENABLED`と`EBAY_DATA_HANDLING_READY`はfalseのまま維持する。

用途の許可条件と利用可能な識別子が分かった後、次を実装・検証する。

- HTTPSの通知受信口。所有確認、通知署名確認、重複受信、失敗時再送に対応し、永続受付または削除完了後だけ成功応答を返す。
- 通知の不変user IDと、保存済みのseller key／usernameを照合する方法。通知のusernameだけを常に受け取れる前提にしない。不明IDを無視して処理済みにしない。
- 削除対象の棚卸し：`market.ebay_seller_profiles`、`market.ebay_seller_research`、`market.ebay_discovered_items`、`market.ebay_sold_observations`、`ingest.raw_ebay_sold_records`、休止中のcollection jobs/pages、セラー由来情報を含む関連記録。元JSONや参照URL中の識別子も確認する。
- ブラウザーに表示中の結果、CSV/JSON、ローカル調査メモ、DBバックアップやテスト環境への複製を含む保管・削除方針。API新規結果をDBへ書かなくても、これらの責任が消えるとは扱わない。
- 実際の運営者・連絡先・用途・保管範囲を記載したプライバシー方針。公開範囲、更新・失効・削除の扱い、許可されたフィールドと出力範囲を反映する。
- eBay側の通知テストと、専用のテストデータでの削除・再送・照合失敗テスト。既存の本番保存データで削除テストをしない。

[公式の削除通知ガイド](https://developer.ebay.com/develop/guides/sell/marketplace-user-account-deletion)を参照。申請先の回答で取扱が変わるため、未確認の免除や存在しない削除処理を申告しない。

## 審査用に添付するもの

- 英文説明を実際の事業情報で完成させる。
- 画面例：実行条件、セラーの選択、選択商品の一覧。保存済みデータの画面はその旨を明記する。
- Sandbox接続成功後のテストURL、操作手順、確認日時。認証情報を一般公開するページや資料には記載しない。
- 用途承認の回答、データ取扱の検証結果。費用・利用枠は当該アカウントへ適用される条件を確認し、無料・無制限と推定しない。

## 削除通知の運用確認

API接続設定の「運用担当者向け：削除通知の状態」から、操作コードの確認後に受付・ID照合待ち・削除待ちの件数を取得できる。通知のユーザーID・本文は表示しない。設定未完了と未処理通知を区別し、通知0件を本番準備完了と表示しない。自動通知や自動削除はまだ行わない。