Guía de la API

Documentación de CartaDex

Empezá por la guía, después usá Cards o Sets. En cada endpoint vas a ver qué hace, qué créditos consume, sus parámetros, un ejemplo y la respuesta.

Cómo empezar

Tres pasos: clave API, header Bearer, primer request.

Base URL de producción: https://api.pokemon-tcg.dev/v1

1. Creá una cuenta y copiá tu clave pkt_live_… desde el panel.
2. Mandala en cada request: Authorization: Bearer pkt_live_…
3. Probá buscar cartas con GET /cards (abajo en la sección Cards).

primer-request.sh

curl "https://api.pokemon-tcg.dev/v1/cards?name=Pikachu&lang=es&limit=5" \
  -H "Authorization: Bearer pkt_live_xxx" \
  -H "Accept: application/json"

Orden recomendado de lectura: Cómo empezar → Cómo se mide el uso → Buscar y listar cartas → Sets.

Créditos de cartas y precios

Cómo se descuentan los créditos en cada consulta.

La API mide consultas de cartas y datos de precios por separado. El plan gratuito incluye cupo de ambos tipos de crédito.

Crédito de carta: cada GET válido de cartas, precios o sets consume 1.
Crédito de precio: include_prices=true consume 1 por carta devuelta; el historial consume 1.
Badge verde = crédito de carta. Badge amarillo = créditos de precio adicionales.
Si se acaba el cupo mensual → HTTP 429.

Cartas GET /v1/cards

Buscar y listar cartas

El endpoint principal de búsqueda. Filtrá por nombre, set, tipo, etc. y recibí una página de resultados.

Usalo cuando querés encontrar cartas. include_prices=true agrega precios y consume créditos de precio por cada carta devuelta.

GET /v1/cards Cartas

Lista paginada de cartas. Cada request gasta 1 crédito de carta. Si mandás include_prices=true, además gasta 1 crédito de precio por cada carta de la página.

Coste: 1 card credit · + N price credits si include_prices=true (N = cartas en la respuesta)

Todos los query params

Param	In	Acceso	Descripción
`name` ej. Pikachu	query	Cartas	Buscar por nombre de la carta (según el idioma).
`set` ej. SSP	query	Cartas	Filtrar por código de expansión.
`type` ej. pokemon	query	Cartas	Filtrar por tipo de carta.
`special` ej. ex	query	Cartas	Filtrar por categoría especial.
`number` ej. 025	query	Cartas	Filtrar por número de coleccionista.
`lang` ej. es	query	Cartas	Idioma del nombre y de las imágenes. Default: en.
`all_languages` ej. false	query	Cartas	Si true, incluye el objeto translations con todos los idiomas.
`include_prices` ej. false	query	Precios	Si true, agrega el array prices a cada carta y gasta créditos de precio.
`page` ej. 1	query	Cartas	Página actual (empieza en 1).
`limit` ej. 20	query	Cartas	Cantidad de cartas por página. Máximo 100. Default típico: 20.

Ejemplo estándar (sin precios) — válido en Free:

search-list-cards.sh

curl "https://api.pokemon-tcg.dev/v1/cards?name=Pikachu&set=SSP&lang=es&page=1&limit=20" \
  -H "Authorization: Bearer pkt_live_xxx" \
  -H "Accept: application/json"

Ejemplo con precios — requiere créditos de precio disponibles:

search-list-cards-prices.sh

curl "https://api.pokemon-tcg.dev/v1/cards?set=SSP&special=ex&include_prices=true&limit=10" \
  -H "Authorization: Bearer pkt_live_xxx"

Respuesta exitosa (200). meta trae la paginación; data es el array de cartas:

search-list-cards.response.json

{
  "status": "success",
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 250,
    "total_pages": 13
  },
  "data": [
    {
      "id": 1,
      "set_code": "SSP",
      "set_name": "Surging Sparks",
      "region": "int",
      "number": "025",
      "card_type": "pokemon",
      "special": "ex",
      "name": "Pikachu ex",
      "translations": {
        "en": "Pikachu ex",
        "es": "Pikachu ex",
        "de": "Pikachu-ex",
        "fr": "Pikachu-ex"
      },
      "images": {
        "xs": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_XS.png",
        "sm": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_SM.png",
        "lg": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_LG.png",
        "original": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN.png"
      },
      "prices": [
        {
          "source_id": "cardmarket",
          "source_name": "Cardmarket",
          "currency": "EUR",
          "variant": "normal",
          "price": 34.5,
          "low_price": 29,
          "high_price": 42,
          "updated_at": "2026-10-05 20:00:00"
        }
      ]
    }
  ]
}

prices solo aparece si include_prices=true.
Errores comunes: 401 (sin API key), 429 (cupo de cartas o de precios agotado).

Cartas GET /v1/cards/{set}/{number}

Carta por set y número

Una carta concreta cuando ya sabés el set y el número (ej. SSP/025).

Más directo que buscar en la lista. Ideal si venís de un set conocido.

GET /v1/cards/{set}/{number} Cartas

Detalle de una carta. Con include_prices=true suma 1 crédito de precio.

Coste: 1 card credit · + 1 price credit si include_prices=true

Path y query params

Param	In	Acceso	Descripción
`set`required ej. SSP	path	Cartas	Código del set.
`number`required ej. 025	path	Cartas	Número de coleccionista.
`lang` ej. es	query	Cartas	Idioma del nombre principal.
`all_languages` ej. false	query	Cartas	Incluir todos los nombres localizados.
`include_prices` ej. false	query	Precios	Incluir precios actuales; consume créditos de precio.

card-by-set-number.sh

curl "https://api.pokemon-tcg.dev/v1/cards/SSP/025?lang=es" \
  -H "Authorization: Bearer pkt_live_xxx"

card-by-set-number.response.json

{
  "status": "success",
  "data": {
    "id": 1,
    "set_code": "SSP",
    "set_name": "Surging Sparks",
    "region": "int",
    "number": "025",
    "card_type": "pokemon",
    "special": "ex",
    "name": "Pikachu ex",
    "translations": {
      "en": "Pikachu ex",
      "es": "Pikachu ex"
    },
    "images": {
      "xs": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_XS.png",
      "sm": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_SM.png",
      "lg": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN_LG.png",
      "original": "https://img.pokemon-tcg.dev/tpci/SSP/SSP_025_R_EN.png"
    }
  }
}

404 si el set/número no existe.
429 si se agotó el cupo.

Cartas GET /v1/cards/{id}

Carta por ID

La misma carta, pero con el ID interno que te devolvió un listado.

Usalo cuando ya tenés el id numérico. La respuesta es igual que por set/número.

GET /v1/cards/{id} Cartas

Detalle por ID. include_prices=true consume créditos de precio.

Coste: 1 card credit · + price credits si include_prices=true

Path y query params

Param	In	Acceso	Descripción
`id`required ej. 1	path	Cartas	ID numérico interno de la carta.
`lang` ej. en	query	Cartas	Idioma del nombre principal.
`all_languages` ej. false	query	Cartas	Incluir todos los nombres localizados.
`include_prices` ej. false	query	Precios	Incluir precios actuales; consume créditos de precio.

card-by-id.sh

curl "https://api.pokemon-tcg.dev/v1/cards/1?lang=es&all_languages=true" \
  -H "Authorization: Bearer pkt_live_xxx"

Precios GET /v1/cards/{id}/prices/history

Histórico de precios

Cómo cambió el precio en el tiempo, si hay datos para la carta y la fuente.

Podés consultarlo con cualquier plan que tenga créditos de precio disponibles, incluido Free.

GET /v1/cards/{id}/prices/history Precios

Historial de precios. Consume 1 crédito de carta y 1 de precio.

Coste: 1 card credit + 1 price credit

Path y query params

Param	In	Acceso	Descripción
`id`required ej. 1	path	Precios	ID de la carta.
`source` ej. cardmarket	query	Precios	Mercado de origen.
`variant` ej. normal	query	Precios	Variante de la carta.
`from` ej. 2026-01-01	query	Precios	Desde esta fecha (YYYY-MM-DD).
`to` ej. 2026-10-05	query	Precios	Hasta esta fecha (YYYY-MM-DD).

price-history.sh

curl "https://api.pokemon-tcg.dev/v1/cards/1/prices/history?source=cardmarket&variant=normal&from=2026-01-01&to=2026-10-05" \
  -H "Authorization: Bearer pkt_live_xxx"

price-history.response.json

{
  "status": "success",
  "card_id": 1,
  "data": [
    {
      "source_id": "cardmarket",
      "source_name": "Cardmarket",
      "currency": "EUR",
      "variant": "normal",
      "price": 34.5,
      "recorded_at": "2026-10-05"
    }
  ]
}

Cartas GET /v1/sets

Listar expansiones (sets)

Todos los sets con su código y cantidad de cartas. Estándar.

Usalo para descubrir códigos (SSP, 151, …) y después filtrar con GET /cards?set=SSP.

GET /v1/sets Cartas

Lista de expansiones. Consume 1 crédito de carta.

Coste: 1 card credit

Query params

Param	In	Acceso	Descripción
`region` ej. int	query	Cartas	Filtrar por región.

sets.sh

curl "https://api.pokemon-tcg.dev/v1/sets?region=int" \
  -H "Authorization: Bearer pkt_live_xxx"

sets.response.json

{
  "status": "success",
  "data": [
    {
      "code": "SSP",
      "name": "Surging Sparks",
      "region": "int",
      "total_cards": 250
    }
  ]
}

401 sin API key.
429 si se agotó el cupo de cartas.

Errores HTTP

Qué significa cada código cuando algo falla.

401 — falta la API key o es inválida
404 CARD_NOT_FOUND — set/número o id inexistente
429 CARD_QUOTA_EXCEEDED — se acabaron los créditos de carta del mes
429 PRICE_QUOTA_EXCEEDED — se acabaron los créditos de precio del mes

error.json

{
  "status": "error",
  "error": {
    "code": "CARD_QUOTA_EXCEEDED",
    "message": "Monthly card quota exhausted"
  }
}