# ebay-active-get Public API

eBayセラー向け管理アプリ「ebay-active-get」が提供する外部アプリ向け公開APIのドキュメント。
このアプリは7つのeBayアカウントの在庫リストを取得・管理し、1時間ごとにアカウント別の在庫高（仕入価格×在庫数の合計）をSupabaseに記録している。

## ベースURL

```
https://ebay-active-get.vercel.app
```

## 認証

すべてのpublic APIは Bearer トークン認証が必要。

```
Authorization: Bearer <PUBLIC_API_KEY>
```

`PUBLIC_API_KEY` はアプリ管理者から払い出してもらう。Vercel環境変数に設定された秘密鍵。

## エンドポイント一覧

### GET /api/public/inventory-snapshot

各eBayアカウントの**直近1時間以内の在庫高スナップショット**を取得する。

#### リクエスト

```http
GET /api/public/inventory-snapshot HTTP/1.1
Authorization: Bearer <PUBLIC_API_KEY>
```

#### レスポンス（200 OK）

```json
{
  "snapshots": [
    {
      "account_name": "monoshare",
      "display_name": "Monoshare",
      "recorded_at": "2026-04-22T08:03:39.936584+00",
      "total_value_jpy": 53927288,
      "item_count": 8918,
      "matched_count": 2518,
      "unmatched_count": 6400,
      "error": null
    },
    {
      "account_name": "pict",
      "display_name": "Pict",
      "recorded_at": "2026-04-22T08:03:39.936584+00",
      "total_value_jpy": 1642672,
      "item_count": 128,
      "matched_count": 127,
      "unmatched_count": 1,
      "error": null
    }
  ],
  "total_value_jpy": 55569960,
  "total_item_count": 9046,
  "account_count": 7,
  "fetched_at": "2026-04-22T09:15:23.456Z"
}
```

#### フィールドの意味

トップレベル:
- `snapshots` (array): アカウント別の最新スナップショット配列
- `total_value_jpy` (number): 全アカウントの在庫高合計（円）
- `total_item_count` (number): 全アカウントの出品件数合計
- `account_count` (number): スナップショットが存在するアカウント数
- `fetched_at` (string): このAPIレスポンスを生成した時刻（ISO 8601）

`snapshots[]` 内:
- `account_name` (string): アカウント識別子（小文字、例: "monoshare"）
- `display_name` (string): UI表示名（例: "Monoshare"）
- `recorded_at` (string): スナップショットが記録された時刻
- `total_value_jpy` (number): このアカウントの在庫高（仕入価格×在庫数の合計、円）
- `item_count` (number): eBay Active 出品件数
- `matched_count` (number): Kintoneで仕入価格が突合できた件数
- `unmatched_count` (number): 仕入価格が見つからなかった件数
- `error` (string | null): 取得時エラー（"トークン未設定"、認証エラー等）

#### エラーレスポンス

- `401 Unauthorized` — Authorizationヘッダーが正しくない
- `500 API未設定(PUBLIC_API_KEY)` — サーバー側で環境変数が設定されていない
- `500 Supabase未設定` — サーバー側でDB接続が設定されていない
- `500 Supabase読取エラー: <message>` — DB読み取り失敗

#### 注意事項

- データは**1時間ごとのCron**で更新される。最新といっても最大1時間前のスナップショット
- 直近24時間以内に記録のないアカウントはレスポンスに含まれない
- Cron失敗時のエラーは `error` フィールドで判別できる（その場合 `total_value_jpy` は 0）

### POST /api/public/returns

ebay-returns-manager から**返品レコードを受信**し `external_returns` に upsert する。
`duplicate: true` は「同一 SKU / itemId の別の返品が既に登録済み」を示し、**重複出品チェック**に使える。

#### リクエスト

```http
POST /api/public/returns HTTP/1.1
Authorization: Bearer <PUBLIC_API_KEY>
Content-Type: application/json

{
  "return_id": "5000123456",
  "ebay_account": "monoshare",
  "item_id": "111222333",
  "sku": "4480145",
  "transaction_id": "...",
  "buyer_login": "buyer1",
  "status": "IMPORTED",
  "item_title": "GOYARD Tote Bag",
  "source": "ebay-returns-manager"
}
```

- `return_id`（必須）が upsert のキー。同じ return_id を再送すると更新される（冪等）。

#### レスポンス（200 OK）

```json
{ "ok": true, "return_id": "5000123456", "duplicate": false, "received_at": "2026-06-03T12:00:00.000Z" }
```

### GET /api/public/returns

指定キーの返品が登録済みか確認する（重複チェック用）。`sku` / `item_id` / `return_id` のいずれかを指定。

```http
GET /api/public/returns?sku=4480145 HTTP/1.1
Authorization: Bearer <PUBLIC_API_KEY>
```

```json
{
  "exists": true,
  "count": 1,
  "returns": [{ "return_id": "5000123456", "sku": "4480145", "status": "IMPORTED" }],
  "fetched_at": "2026-06-03T12:00:00.000Z"
}
```

> 受信データは Supabase テーブル `external_returns` に格納される。
> （初回のみ `supabase/migrations/2026-06-03-external-returns.sql` を実行してテーブル作成が必要）

## 呼び出しサンプル（JavaScript）

```javascript
const res = await fetch(
  "https://ebay-active-get.vercel.app/api/public/inventory-snapshot",
  { headers: { Authorization: `Bearer ${process.env.EBAY_ACTIVE_GET_API_KEY}` } }
);
const data = await res.json();
console.log(`全アカウント在庫高合計: ¥${data.total_value_jpy.toLocaleString()}`);
for (const s of data.snapshots) {
  console.log(`${s.display_name}: ¥${s.total_value_jpy.toLocaleString()} (${s.item_count}件)`);
}
```

## 呼び出しサンプル（curl）

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ebay-active-get.vercel.app/api/public/inventory-snapshot
```

## 機械可読版

JSON形式のAPIスペックは以下から取得可能:
```
GET https://ebay-active-get.vercel.app/api/docs
```