API/Documentation

Documentation API

Base URL : https://pokevall.com/api/v1

🚀 Demarrage rapide

L'API PokeVall est disponible exclusivement pour les abonnes Max (29.90 CHF/mois).

3 etapes pour commencer :

Souscrivez au plan Max sur /pricing
Generez votre cle API dans vos parametres
Ajoutez le header X-Api-Key a vos requetes

const response = await fetch(
  'https://pokevall.com/api/v1/cards?search=pikachu&lang=FR',
  {
    headers: {
      'X-Api-Key': 'pk_live_VOTRE_CLE',
      'Content-Type': 'application/json'
    }
  }
)
const data = await response.json()
console.log(data.cards) // Array de cartes avec prix

🔑 Authentification

Toutes les requetes necessitent votre cle API dans le header HTTP.

Header	Valeur	Requis
`X-Api-Key`	`pk_live_...`	✅ Oui
`Content-Type`	`application/json`	Recommande

⚠️ Securite

Ne jamais exposer votre cle cote client (navigateur). Faites toujours les appels depuis votre backend ou une Edge Function.

🃏 GET /cards

GET https://pokevall.com/api/v1/cards

Parametres

Param	Type	Requis	Description
search	string	✅	Nom de la carte
lang	string	Non	FR, EN, DE, JP
set	string	Non	Nom ou ID du set
rarity	string	Non	Rarete (Holo Rare, Ultra Rare...)
limit	number	Non	Max 50, defaut 10
page	number	Non	Pagination

Reponse

{
  "cards": [
    {
      "id": "sv3pt5-001",
      "name": "Pikachu ex",
      "setName": "151",
      "number": "025",
      "rarity": "Double Rare",
      "language": "FR",
      "imageUrl": "https://...",
      "prices": {
        "cardmarket": { "eur": 12.50, "trend": 13.20 },
        "tcgplayer": { "market": 14.30, "low": 11.00 },
        "ebay": { "recent_avg": 13.80 }
      },
      "updatedAt": "2026-05-11T12:00:00Z"
    }
  ],
  "totalFound": 47,
  "page": 1,
  "limit": 10
}

📦 GET /sealed

GET https://pokevall.com/api/v1/sealed

Param	Type	Description
search	string ✅	Nom du produit (ex: "evolving skies booster box")
lang	string	EN, JP
type	string	display, etb, bundle, pack
limit	number	Max 50

{
  "products": [
    {
      "name": "Evolving Skies Booster Box",
      "setName": "Evolving Skies",
      "productType": "display",
      "price_chf": 245,
      "price_usd": 279.99,
      "imageUrl": "https://...",
      "source": "TCGPlayer",
      "updatedAt": "2026-05-11T12:00:00Z"
    }
  ],
  "totalFound": 5
}

⭐ GET /graded

GET https://pokevall.com/api/v1/graded

Prix des cartes gradees basees sur les ventes eBay reelles. Couvre PSA, BGS, CGC, SGC et TAG.

Param	Type	Description
search	string ✅	Nom de la carte
company	string	PSA, BGS, CGC, SGC, TAG
grade	number	1-10 (demi-notes pour BGS/CGC)

{
  "card": "Charizard Base Set",
  "gradedPrices": [
    { "company": "PSA", "grade": 10, "price_chf": 12500, "sales": 28, "trend": "stable" },
    { "company": "PSA", "grade": 9, "price_chf": 4200, "sales": 145, "trend": "rising" },
    { "company": "BGS", "grade": 9.5, "price_chf": 9800, "sales": 12, "trend": "stable" },
    { "company": "CGC", "grade": 9.5, "price_chf": 3100, "sales": 34, "trend": "falling" }
  ],
  "source": "eBay Sold",
  "updatedAt": "2026-05-11T12:00:00Z"
}

📂 GET /sets

GET https://pokevall.com/api/v1/sets

{
  "sets": [
    {
      "id": "sv3pt5",
      "name": "151",
      "series": "Scarlet & Violet",
      "totalCards": 207,
      "releaseDate": "2023-09-22",
      "logoUrl": "https://..."
    }
  ],
  "totalSets": 150
}

📈 GET /prices/history

GET https://pokevall.com/api/v1/prices/history

Jusqu'a 6 mois d'historique prix quotidien par source (TCGPlayer, eBay).

Param	Type	Description
cardId	string ✅	ID de la carte
period	string	7d, 30d, 90d, 180d (defaut 30d)
source	string	tcgplayer, ebay, cardmarket

{
  "cardId": "sv3pt5-001",
  "history": {
    "tcgplayer": [
      { "date": "2026-05-11", "price": 12.50 },
      { "date": "2026-05-10", "price": 12.30 },
      { "date": "2026-05-09", "price": 11.90 }
    ],
    "ebay": [
      { "date": "2026-05-11", "price": 13.80 },
      { "date": "2026-05-10", "price": 14.10 }
    ]
  },
  "period": "30d",
  "dataPoints": 60
}

📊 GET /population

GET https://pokevall.com/api/v1/population

Donnees de population GemRate : nombre de cartes gradees par certifieur et par note. Ideal pour calculer le ROI de grading.

{
  "card": "Charizard VMAX",
  "population": {
    "PSA": { "g10": 2500, "g9": 8000, "total": 12000, "gemRate": 20.83 },
    "BGS": { "g10": 100, "g9_5": 500, "total": 1830, "gemRate": 7.10 },
    "CGC": { "g10": 50, "g9_5": 200, "total": 650, "gemRate": 7.69 },
    "SGC": { "g10": 30, "g9": 100, "total": 130, "gemRate": 23.08 }
  },
  "totalGraded": 14610,
  "combinedGemRate": 18.55
}

⚠️ Codes d'erreur

Code	Erreur	Description
400	BAD_REQUEST	Parametre manquant ou invalide
401	UNAUTHORIZED	Cle API manquante ou invalide
403	FORBIDDEN	Plan insuffisant (API reservee Max)
429	RATE_LIMITED	Limite de 10 000 requetes/jour atteinte
500	SERVER_ERROR	Erreur interne PokeVall

{
  "error": "UNAUTHORIZED",
  "message": "Cle API invalide ou expiree",
  "code": 401
}

🚦 Rate Limits

Plan	Req/jour	Req/min	Acces API
Gratuit	—	—	❌
Pro	—	—	❌
Max	10 000	60	✅

Les headers de rate limit sont inclus dans chaque reponse :

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9987
X-RateLimit-Reset: 2026-05-12T00:00:00Z

💡 Exemples de code

Bot Discord — prix en temps reel

const { Client, Events, GatewayIntentBits } = require('discord.js')
const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages]
})

client.on(Events.MessageCreate, async (message) => {
  if (!message.content.startsWith('!prix')) return
  const cardName = message.content.slice(6).trim()

  const res = await fetch(
    `https://pokevall.com/api/v1/cards?search=${encodeURIComponent(cardName)}&lang=FR`,
    { headers: { 'X-Api-Key': process.env.POKEVALL_API_KEY } }
  )
  const { cards } = await res.json()

  if (!cards.length) return message.reply('Carte introuvable.')

  const card = cards[0]
  const price = card.prices.cardmarket?.eur ?? 'N/A'
  message.reply(`💰 **${card.name}** — ${price} €  (CardMarket)`)
})

client.login(process.env.DISCORD_TOKEN)

← Retour a la page API