Guida Sviluppatore API PokeTrace

GET /v1/cards

Elenca le carte con paginazione e filtri. Restituisce info base della carta senza prezzi completi.

Params: limit (max 100), cursor, set, search, card_number, variant, market (US/EU), has_graded

{
  "data": [{
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "cardNumber": "4/102",
    "set": { "slug": "base-set", "name": "Base Set" },
    "variant": "Holofoil",
    "rarity": "Rare Holo",
    "market": "US",
    "currency": "USD"
  }],
  "pagination": { "hasMore": true, "nextCursor": "YnNfNQ==", "count": 1 }
}

GET /v1/cards/:id

Ottieni dettagli completi della carta con prezzi per fonte e tier. Le carte USA includono ebay (tutti i tier) + tcgplayer (solo raw). Le carte EU includono cardmarket (trend dei prezzi con medie storiche) + cardmarket_unsold (annunci attivi con suddivisione per tier/paese).

// Carta US
{
  "data": {
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "market": "US",
    "currency": "USD",
    "prices": {
      "ebay": {
        "PSA_10": { "avg": 5200, "low": 4800, "high": 5600, "saleCount": 47 },
        "NEAR_MINT": { "avg": 890, "low": 750, "high": 1050, "saleCount": 156 }
      },
      "tcgplayer": {
        "NEAR_MINT": { "avg": 420, "low": 380, "high": 480, "saleCount": 89 }
      }
    }
  }
}

// Carta EU
{
  "data": {
    "id": "eu_273550",
    "name": "Charizard",
    "market": "EU",
    "currency": "EUR",
    "prices": {
      "cardmarket": { "avg": 385, "avg1d": 380, "avg7d": 375, "avg30d": 370 },
      "cardmarket_unsold": {
        "NEAR_MINT": { "avg": 420, "low": 350, "high": 890, "saleCount": 125, "country": { "DE": { "avg": 410 }, "FR": { "avg": 450 } } }
      }
    }
  }
}

GET /v1/sets

Elenca tutti i set di carte con metadati. Usa gli slug dei set per filtrare le carte.

Params: search, game (pokemon, pokemon-japanese), limit, cursor

{
  "data": [
    { "slug": "base-set", "name": "Base Set", "releaseDate": "1999-01-09", "cardCount": 102 },
    { "slug": "base-set-2", "name": "Base Set 2", "releaseDate": "2000-02-24", "cardCount": 130 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "YmFzZS1zZXQtMg==", "count": 2 }
}

GET /v1/auth/info

Ottieni info sulla tua chiave API e statistiche di utilizzo. Controlla le richieste rimanenti, il tempo di reset e i dettagli del piano.

{
  "data": {
    "key": "pc_a1b2c3d4...",
    "name": "Production",
    "active": true,
    "createdAt": "2026-01-17T10:00:00Z",
    "lastUsedAt": "2026-01-17T12:30:00Z",
    "user": {
      "plan": "Free",
      "remaining": 208,
      "limit": 250,
      "resetsAt": "2026-01-18T00:00:00Z"
    }
  }
}

GET /v1/cards/:id/prices/:tier/history

Ottieni dati storici sui prezzi per un tier specifico. Utile per grafici e analisi delle tendenze.

Params: period (7d, 30d, 90d, 1y, all), limit, cursor

{
  "data": [
    { "date": "2026-01-27", "source": "ebay", "avg": 5200, "low": 4800, "high": 5600, "saleCount": 3 },
    { "date": "2026-01-26", "source": "ebay", "avg": 5150, "low": 4750, "high": 5500, "saleCount": 5 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "MjAyNi0wMS0yNQ==", "count": 2 }
}

Qual e la differenza tra carte USA ed EU?

Le carte sono specifiche per mercato. Le carte USA hanno prezzi TCGPlayer ed eBay in USD. Le carte EU hanno prezzi CardMarket in EUR con suddivisioni per paese (DE, FR, IT, ecc.). Ogni carta appartiene a un solo mercato.

Quali aziende di certificazione sono supportate?

Supportiamo 15 aziende di certificazione tra cui PSA, BGS, CGC, ACE, TAG e altre. I prezzi delle carte certificate sono disponibili nei piani Pro e Scale. Il campo gradedOptions su ogni carta mostra i gradi disponibili.

Come ottengo aggiornamenti dei prezzi in tempo reale?

Le connessioni WebSocket sono disponibili nel piano Scale. Connettiti a wss://api.poketrace.com/ws con la tua chiave API. Iscriviti a carte specifiche per ricevere aggiornamenti istantanei quando avvengono nuove vendite.

Posso usare l'API per progetti commerciali?

Si. Il tier gratuito permette uso non commerciale. I piani Pro e Scale includono licenze commerciali. Consulta i nostri termini di servizio per tutti i dettagli.

Quanto sono accurati i dati sui prezzi?

I prezzi si basano su vendite completate verificate da TCGPlayer, eBay e CardMarket. Aggiorniamo ogni poche ore. Ogni tier di prezzo include un punteggio di confidenza (alto, medio, basso) e saleCount per valutare l'affidabilita.