Lunidex 公開 API v1

連携には API キー、サーバー側に保存したシークレット、API ベース URL への HTTPS リクエストが必要です。

1. 1

   キーを作成する

   Lunidex ダッシュボードの API キーカードを開き、名前と読み取り専用または読み書き権限を選びます。完全なシークレットは一度だけ表示されるため、メッセージを閉じる前にコピーしてください。

2. 2

   サーバーにシークレットを保存する

   ホスティングサービスのシークレット管理機能に LUNIDEX_API_KEY として保存してください。リポジトリにコミットしたり、ブラウザーへ送信したりしないでください。

3. 3

   最初のリクエストを送る

   サーバーから GET /me を呼び出します。非公開エンドポイントには Authorization: Bearer の後にキーを付けます。

curl --fail-with-body \
  -H "Authorization: Bearer $LUNIDEX_API_KEY" \
  https://lunidex.app/api/v1/me

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

const response = await fetch(API_BASE_URL + "/me", {
  headers: { Authorization: "Bearer " + apiKey },
});
const result = await response.json();

if (!response.ok) {
  throw new Error(result.error?.code ?? "REQUEST_FAILED");
}

console.log(result.data);

非公開の /api/v1 リクエストごとに HTTP Authorization ヘッダーでキーを送信します。API は data エンベロープの JSON を返し、非公開レスポンスには Cache-Control: private, no-store を設定します。

API で参照できるのは Neon の Lunidex アカウントに同期されたデータのみです。端末だけにあるデータは取得できません。アカウント情報にメールアドレスは含まれません。

一覧は data と meta.nextCursor を返します。次のページではカーソルを変更せずに渡し、null になったら終了します。

• 既定のページサイズは 25、最大は 100 です。カタログ検索は 1 ページあたり 24 件に固定されています。
• カードは language と set で絞り込めます。未開封商品の保有状況は language と productId、取引は language、productId、type、includeVoided、voided で絞り込めます。カタログ検索は q と cursor を受け付けます。
• コレクション、取引記録、価格、フィルターが変わるとカーソルが古くなることがあります。その場合 API は 409 を返します。最新データを使い、カーソルなしで最初から取得してください。

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;
let cursor = null;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

do {
  const query = new URLSearchParams({ limit: "100" });
  if (cursor) query.set("cursor", cursor);

  const response = await fetch(API_BASE_URL + "/cards?" + query, {
    headers: { Authorization: "Bearer " + apiKey },
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error?.code ?? "REQUEST_FAILED");

  console.log(result.data);
  cursor = result.meta?.nextCursor ?? null;
} while (cursor);

各パスは API のベース URL からの相対パスです。各行に必要なアクセス権と OpenAPI 契約に記載されたパラメーターを示します。機械可読な仕様には完全なスキーマ、リクエストとレスポンスの例、操作ごとのエラーが含まれます。以下のセクションでは主な使い方を説明します。

GET /cards は TCGdex のカタログ全体を読み込まず、保有中のバリアントを一覧表示します。各項目には cardId、setId、language、variant、quantity が含まれ、language と set で絞り込めます。

GET /cards/{cardId} は TCGdex の有用なメタデータと、アカウント内でのそのカードの保有状況を返します。language クエリで絞り込めます。

{
  "language": "en",
  "variant": "reverse",
  "quantity": 2
}

言語情報のない古い保有データも表示されます。language が null になり、legacy として示される場合があります。

この API はカードの価格を返しません。

未開封商品の保有状況には言語ごとの数量、原価、Lunidex に保存済みの価格に基づく現在価値が含まれます。金額は EUR の整数セントです。価格がない場合 valueCents は null となり missingPrice で示されます。summary には missingPrices も含まれます。

GET /summary では、保有商品のうち 1 つでも価格がない場合、未開封商品の価値は null になります。missingPrices に不足件数が含まれます。

成功時は { "data": ..., "meta": ... }（meta は省略可能）を返します。エラー時は { "error": { "code": ..., "message": ..., "details": ... } }（details は省略可能）を返します。

主な応答: 400 取引データ不正、401 キー無効、403 権限不足、404 リソースなしまたは未保有、409 カーソルまたは revision が古い、410 アカウント削除中、422 クエリパラメーターまたはリクエスト本文が不正、429 上限到達、500 予期しないサーバーエラー、502 カードデータ利用不可、503 API 利用不可。

すべての非公開 API レスポンスは Cache-Control: private, no-store を使用します。公開 OpenAPI 仕様は /api/v1/openapi.json から取得できます。

上限は Lunidex アカウントごとに適用され、同じアカウントの API キー間で共有されます。

カード詳細と未開封商品の計算には、それぞれ別の全体上限として 1 カテゴリあたり 1 日 5,000 回が設定されています。429 応答には Retry-After が含まれます。