API pública Lunidex v1

La integración necesita una clave, un secreto almacenado en el servidor y una solicitud HTTPS a la URL base de la API.

1. 1

   Crear una clave

   Abre la tarjeta de claves API en el panel de Lunidex. Asigna un nombre y elige solo lectura o lectura y escritura. El secreto completo se muestra una sola vez; cópialo antes de cerrar el aviso.

2. 2

   Guardar el secreto en el servidor

   Guarda la clave como LUNIDEX_API_KEY en el gestor de secretos de tu proveedor de alojamiento. No la incluyas en el repositorio ni la envíes al navegador.

3. 3

   Enviar la primera solicitud

   Llama a GET /me desde tu servidor. Las rutas privadas requieren el encabezado Authorization: Bearer seguido de la clave.

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

Envía la clave en el encabezado HTTP Authorization para cada solicitud privada /api/v1. La API responde con JSON dentro de data; las respuestas privadas usan Cache-Control: private, no-store.

La API solo ve los datos sincronizados con la cuenta Lunidex en Neon. Los datos que solo existen en un dispositivo no están disponibles. La identidad de la cuenta no incluye el correo electrónico.

Las listas devuelven data y meta.nextCursor. Envía ese cursor sin modificar para solicitar la página siguiente y termina cuando sea null.

• El tamaño predeterminado es 25 y el máximo 100. El catálogo devuelve como máximo 24 resultados por página.
• Las cartas aceptan los filtros language y set. Las posiciones selladas aceptan language y productId; las transacciones aceptan language, productId, type, includeVoided y voided. El catálogo acepta q y cursor.
• El cursor puede quedar obsoleto si cambian la colección, el registro, los precios o los filtros. La API devuelve 409; vuelve a empezar sin cursor con el estado más reciente.

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

Las rutas son relativas a la URL base de la API. Cada fila muestra el acceso requerido y los parámetros del contrato OpenAPI. La especificación legible por máquinas incluye los esquemas completos, ejemplos de solicitud y respuesta, y errores por operación; las secciones siguientes explican los flujos principales.

GET /cards enumera las variantes en propiedad sin cargar todo el catálogo de TCGdex. Cada posesión incluye cardId, setId, language, variant y quantity; los filtros opcionales son language y set.

GET /cards/{cardId} devuelve metadatos útiles de TCGdex y las posesiones de esa carta en la cuenta. Añade el parámetro language para limitar las posesiones.

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

Las posesiones antiguas sin idioma siguen disponibles; language puede ser null y pueden aparecer marcadas como legacy.

Esta API nunca devuelve valoraciones de cartas.

Las posiciones incluyen cantidades por idioma, coste y valor actual a partir de los precios ya guardados en Lunidex. Los importes son céntimos enteros de EUR. Si falta el precio, valueCents es null y missingPrice lo indica; el resumen también cuenta missingPrices.

En GET /summary, el valor sellado es null si falta el precio de algún producto en propiedad; missingPrices indica cuántos.

Las respuestas correctas usan { "data": ..., "meta": ... } (meta es opcional). Los errores usan { "error": { "code": ..., "message": ..., "details": ... } } (details es opcional).

Respuestas habituales: 400 datos de transacción no válidos; 401 clave no válida; 403 permiso insuficiente; 404 recurso inexistente o no poseído; 409 cursor o revisión obsoletos; 410 cuenta en proceso de eliminación; 422 parámetro de consulta o cuerpo no válido; 429 cuota alcanzada; 500 error inesperado del servidor; 502 datos de carta no disponibles; 503 API no disponible.

Todas las respuestas privadas usan Cache-Control: private, no-store. El documento OpenAPI público está disponible por separado en /api/v1/openapi.json.

Los límites se aplican por cuenta Lunidex y se comparten entre sus claves API.

Los detalles de cartas y los cálculos de sellados también tienen límites globales independientes de 5 000 operaciones diarias por categoría. La respuesta 429 incluye Retry-After.