API publique Lunidex v1

Une intégration a besoin d’une clé, d’un secret stocké côté serveur et d’une requête HTTPS vers l’URL de base de l’API.

1. 1

   Créer une clé

   Ouvrez la carte des clés API dans le tableau de bord Lunidex. Nommez la clé et choisissez lecture seule ou lecture et écriture. Le secret complet n’apparaît qu’une fois : copiez-le avant de fermer le message.

2. 2

   Stocker le secret sur votre serveur

   Enregistrez la clé sous LUNIDEX_API_KEY dans le gestionnaire de secrets de votre hébergeur. Ne la commitez pas et ne l’envoyez pas au navigateur.

3. 3

   Envoyer la première requête

   Appelez GET /me depuis votre serveur. Les routes privées exigent l’en-tête Authorization: Bearer suivi de la clé.

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

Envoyez la clé dans l’en-tête HTTP Authorization pour chaque requête privée /api/v1. L’API renvoie du JSON dans une enveloppe data ; les réponses privées utilisent Cache-Control: private, no-store.

L’API ne voit que les données synchronisées avec le compte Lunidex dans Neon. Les données présentes uniquement sur un appareil ne sont pas accessibles. L’identité du compte ne contient pas l’adresse e-mail.

Les listes renvoient data et meta.nextCursor. Transmettez ce curseur sans le modifier pour obtenir la page suivante, puis arrêtez-vous quand il vaut null.

• La taille par défaut est de 25 éléments et le maximum de 100. Le catalogue est limité à 24 résultats par page.
• Les cartes acceptent les filtres language et set. Les positions scellées acceptent language et productId ; les transactions acceptent language, productId, type, includeVoided et voided. Le catalogue accepte q et cursor.
• Un curseur peut devenir obsolète si la collection, le journal, les prix ou les filtres changent. L’API renvoie 409 ; recommencez sans curseur avec les données à jour.

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

Les chemins sont relatifs à l’URL de base de l’API. Chaque ligne indique le niveau d’accès et les paramètres du contrat OpenAPI. La spécification lisible par machine contient les schémas complets, des exemples de requête et de réponse, ainsi que les erreurs par opération ; les sections ci-dessous expliquent les principaux usages.

GET /cards liste les variantes possédées sans charger tout le catalogue TCGdex. Chaque possession contient cardId, setId, language, variant et quantity ; les filtres facultatifs sont language et set.

GET /cards/{cardId} renvoie les métadonnées TCGdex utiles et les possessions de cette carte dans le compte. Ajoutez le paramètre language pour limiter les possessions.

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

Les anciennes possessions sans langue restent visibles ; leur langue peut valoir null et elles peuvent être marquées legacy.

Cette API ne renvoie jamais la valeur des cartes.

Les positions indiquent les quantités par langue, le coût et la valeur actuelle calculée à partir des prix déjà stockés dans Lunidex. Les montants sont des centimes entiers d’EUR. Si un prix manque, valueCents vaut null et missingPrice l’indique ; le résumé compte aussi missingPrices.

Dans GET /summary, la valeur des scellés vaut null si le prix manque pour au moins un produit possédé ; missingPrices donne le nombre de prix manquants.

Une réponse réussie utilise { "data": ..., "meta": ... } (meta est facultatif). Une erreur utilise { "error": { "code": ..., "message": ..., "details": ... } } (details est facultatif).

Réponses courantes : 400 données de transaction invalides ; 401 clé invalide ; 403 permission insuffisante ; 404 ressource absente ou non détenue ; 409 curseur ou révision obsolète ; 410 compte en cours de suppression ; 422 paramètre de requête ou corps invalide ; 429 quota atteint ; 500 erreur serveur inattendue ; 502 données de carte indisponibles ; 503 API indisponible.

Toutes les réponses privées utilisent Cache-Control: private, no-store. La spécification OpenAPI publique est disponible séparément sur /api/v1/openapi.json.

Les limites s’appliquent par compte Lunidex et sont partagées entre ses clés API.

Les détails de cartes et les calculs de scellés ont aussi chacun un plafond global distinct de 5 000 opérations par jour. Une réponse 429 inclut Retry-After.