Lunidex Public API v1

Die Integration benötigt einen Schlüssel, ein serverseitig gespeichertes Secret und eine HTTPS-Anfrage an die API-Basis-URL.

1. 1

   Schlüssel erstellen

   Öffne die API-Schlüsselkarte im Lunidex-Dashboard. Vergib einen Namen und wähle Lesezugriff oder Lese- und Schreibzugriff. Das vollständige Secret wird nur einmal angezeigt. Kopiere es, bevor du die Meldung schließt.

2. 2

   Secret auf dem Server speichern

   Speichere den Schlüssel als LUNIDEX_API_KEY im Secret-Manager deines Hosting-Anbieters. Committe ihn nicht und sende ihn nicht an den Browser.

3. 3

   Erste Anfrage senden

   Rufe GET /me von deinem Backend auf. Private Endpunkte benötigen den Header Authorization: Bearer gefolgt vom Schlüssel.

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);

Sende den Schlüssel bei jeder privaten /api/v1-Anfrage im HTTP-Header Authorization. Die API liefert JSON in einem data-Umschlag; private Antworten verwenden Cache-Control: private, no-store.

Die API sieht nur Daten, die mit dem Lunidex-Konto in Neon synchronisiert wurden. Daten, die nur auf einem Gerät liegen, sind nicht verfügbar. Die Kontoidentität enthält keine E-Mail-Adresse.

Listen liefern data und meta.nextCursor. Übernimm den Cursor unverändert für die nächste Seite und beende die Abfrage, wenn er null ist.

• Die Standardseitengröße beträgt 25, maximal sind 100 möglich. Die Katalogsuche liefert höchstens 24 Ergebnisse pro Seite.
• Karten akzeptieren die Filter language und set. Sealed-Positionen akzeptieren language und productId; Transaktionen akzeptieren language, productId, type, includeVoided und voided. Die Katalogsuche akzeptiert q und cursor.
• Ein Cursor kann veraltet sein, wenn sich Sammlung, Journal, Preise oder Filter ändern. Die API liefert dann 409. Starte ohne Cursor mit dem aktuellen Stand neu.

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);

Die Pfade sind relativ zur API-Basis-URL. Jede Zeile zeigt die erforderliche Berechtigung und die im OpenAPI-Vertrag aufgeführten Parameter. Die maschinenlesbare Spezifikation enthält vollständige Schemas, Anfrage- und Antwortbeispiele sowie Fehler pro Operation; die folgenden Abschnitte erklären die wichtigsten Abläufe.

GET /cards listet besessene Varianten auf, ohne den vollständigen TCGdex-Katalog zu laden. Jeder Bestand enthält cardId, setId, language, variant und quantity; die optionalen Filter sind language und set.

GET /cards/{cardId} liefert nützliche TCGdex-Metadaten und die Bestände dieser Karte im Konto. Mit dem Abfrageparameter language kannst du die Bestände eingrenzen.

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

Ältere Bestände ohne Sprache bleiben sichtbar; language kann null sein und der Eintrag kann als legacy markiert sein.

Diese API gibt keine Kartenwerte zurück.

Sealed-Positionen enthalten Mengen nach Sprache, Kosten und aktuellen Wert auf Basis der bereits in Lunidex gespeicherten Preise. Beträge sind ganze EUR-Cent. Fehlt ein Preis, ist valueCents null und missingPrice gesetzt; die Zusammenfassung zählt außerdem missingPrices.

In GET /summary ist der Sealed-Wert null, wenn für mindestens ein besessenes Produkt kein Preis vorhanden ist; missingPrices enthält die Anzahl.

Erfolgreiche Antworten verwenden { "data": ..., "meta": ... } (meta ist optional). Fehler verwenden { "error": { "code": ..., "message": ..., "details": ... } } (details ist optional).

Häufige Antworten: 400 ungültige Transaktionsdaten; 401 ungültiger Schlüssel; 403 fehlende Berechtigung; 404 Ressource fehlt oder gehört nicht zum Konto; 409 Cursor oder Revision veraltet; 410 Konto wird gelöscht; 422 ungültiger Abfrageparameter oder Request-Body; 429 Kontingent erreicht; 500 unerwarteter Serverfehler; 502 Kartendaten nicht verfügbar; 503 API nicht verfügbar.

Alle privaten API-Antworten verwenden Cache-Control: private, no-store. Das öffentliche OpenAPI-Dokument ist separat unter /api/v1/openapi.json verfügbar.

Die Limits gelten pro Lunidex-Konto und werden von dessen API-Schlüsseln gemeinsam genutzt.

Kartendetails und Sealed-Berechnungen haben außerdem getrennte globale Obergrenzen von jeweils 5.000 Vorgängen pro Tag. Eine 429-Antwort enthält Retry-After.