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입니다. 카탈로그 검색은 페이지당 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에서 보유 상품 중 하나라도 가격이 없으면 미개봉 상품 가치는 null입니다. missingPrices에 누락된 가격 개수가 포함됩니다.

성공 응답은 { "data": ..., "meta": ... }를 사용하며 meta는 선택 사항입니다. 오류는 { "error": { "code": ..., "message": ..., "details": ... } }를 사용하며 details는 선택 사항입니다.

일반 응답: 400 거래 데이터 오류, 401 키가 유효하지 않음, 403 권한 부족, 404 리소스가 없거나 계정 소유가 아님, 409 커서 또는 리비전이 오래됨, 410 계정 삭제 중, 422 쿼리 매개변수 또는 요청 본문 오류, 429 할당량 초과, 500 예상치 못한 서버 오류, 502 카드 데이터 이용 불가, 503 API 이용 불가.

모든 비공개 API 응답은 Cache-Control: private, no-store를 사용합니다. 공개 OpenAPI 문서는 /api/v1/openapi.json에서 별도로 제공합니다.

한도는 Lunidex 계정별로 적용되며 해당 계정의 모든 API 키가 공유합니다.

카드 상세 조회와 미개봉 계산은 각각 별도의 전체 한도가 있으며 범주마다 하루 5,000회입니다. 429 응답에는 Retry-After가 포함됩니다.