API pubblica Lunidex v1

L’integrazione richiede una chiave, un segreto conservato sul server e una richiesta HTTPS all’URL di base dell’API.

1. 1

   Crea una chiave

   Apri la scheda delle chiavi API nella dashboard Lunidex. Assegna un nome e scegli sola lettura oppure lettura e scrittura. Il segreto completo viene mostrato una sola volta: copialo prima di chiudere il messaggio.

2. 2

   Conserva il segreto sul server

   Salva la chiave come LUNIDEX_API_KEY nel gestore di segreti del tuo provider. Non inserirla nel repository e non inviarla al browser.

3. 3

   Invia la prima richiesta

   Chiama GET /me dal tuo server. Gli endpoint privati richiedono l’intestazione Authorization: Bearer seguita dalla chiave.

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

Invia la chiave nell’intestazione HTTP Authorization per ogni richiesta privata /api/v1. L’API restituisce JSON nell’involucro data; le risposte private usano Cache-Control: private, no-store.

L’API vede solo i dati sincronizzati con l’account Lunidex in Neon. I dati presenti soltanto su un dispositivo non sono disponibili. L’identità dell’account non include l’indirizzo email.

Gli elenchi restituiscono data e meta.nextCursor. Passa il cursore senza modificarlo per chiedere la pagina successiva e termina quando è null.

• La dimensione predefinita è 25 e il massimo è 100. Il catalogo restituisce al massimo 24 risultati per pagina.
• Le carte accettano i filtri language e set. Le posizioni sigillate accettano language e productId; le transazioni accettano language, productId, type, includeVoided e voided. Il catalogo accetta q e cursor.
• Il cursore può diventare obsoleto se cambiano raccolta, registro, prezzi o filtri. L’API restituisce 409; ricomincia senza cursore usando lo stato aggiornato.

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

I percorsi sono relativi all’URL di base dell’API. Ogni riga indica il livello di accesso richiesto e i parametri elencati nel contratto OpenAPI. La specifica leggibile dalle macchine contiene gli schemi completi, esempi di richieste e risposte ed errori per operazione; le sezioni seguenti spiegano i flussi principali.

GET /cards elenca le varianti possedute senza caricare l’intero catalogo TCGdex. Ogni possesso include cardId, setId, language, variant e quantity; i filtri facoltativi sono language e set.

GET /cards/{cardId} restituisce metadati TCGdex utili e i possedimenti di questa carta nell’account. Aggiungi il parametro language per restringere i possedimenti.

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

I vecchi possedimenti senza lingua restano visibili; language può essere null e possono essere contrassegnati legacy.

Questa API non restituisce mai il valore delle carte.

Le posizioni includono quantità per lingua, costo e valore corrente calcolato dai prezzi già memorizzati in Lunidex. Gli importi sono centesimi interi di EUR. Se manca un prezzo, valueCents è null e missingPrice lo indica; il riepilogo conta anche missingPrices.

In GET /summary, il valore dei prodotti sigillati è null se manca il prezzo di almeno un prodotto posseduto; missingPrices indica il totale.

Le risposte riuscite usano { "data": ..., "meta": ... } (meta è facoltativo). Gli errori usano { "error": { "code": ..., "message": ..., "details": ... } } (details è facoltativo).

Risposte comuni: 400 dati della transazione non validi; 401 chiave non valida; 403 permesso insufficiente; 404 risorsa assente o non posseduta; 409 cursore o revisione obsoleti; 410 account in eliminazione; 422 parametro di query o corpo della richiesta non valido; 429 quota raggiunta; 500 errore server imprevisto; 502 dati della carta non disponibili; 503 API non disponibile.

Tutte le risposte private dell’API usano Cache-Control: private, no-store. Il documento OpenAPI pubblico è disponibile separatamente su /api/v1/openapi.json.

I limiti si applicano per account Lunidex e sono condivisi dalle sue chiavi API.

I dettagli delle carte e i calcoli dei prodotti sigillati hanno anche limiti globali distinti di 5.000 operazioni al giorno per categoria. Una risposta 429 include Retry-After.