Documentation de l'API publique

Ta clé voyage dans l'en-tête x-api-key (ou Authorization: Bearer …). Elle s'utilise depuis ton serveur, jamais depuis une page ou une application mobile : une clé lue par un visiteur est une clé perdue.

curl -H "x-api-key: pkm_..." \
  https://public.pokemania.top/api/public/v1/whoami

Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà du quota, l'API répond 429 avec un Retry-After : mets en cache plutôt que de boucler.

Envoie le joueur sur le portail de connexion avec ton client_id, les accès demandés et une URL de retour déclarée dans ta demande :

https://login.pokemania.top/authorize
  ?client_id=app_...
  &redirect_uri=https://ton-site/callback
  &scope=player.bank%20player.village
  &state=ton-etat

Le joueur s'identifie (Discord ou code en jeu), voit ton logo et la liste exacte de ce que tu demandes, puis accepte ou refuse. Au retour, ton URL reçoit ?code=ac_…&state=… (ou ?error=access_denied). Échange ce code sous deux minutes :

curl -X POST https://public.pokemania.top/api/public/v1/oauth/token \
  -H "x-api-key: pkm_..." \
  -H "content-type: application/json" \
  -d '{"code":"ac_..."}'

Tu récupères un access_token (pat_…) à conserver : il s'envoie ensuite dans x-player-token, en plus de ta clé, sur les routes /me…. Un jeton n'est valable qu'avec la clé qui l'a obtenu, et le joueur peut le révoquer à tout moment.

curl -X POST https://public.pokemania.top/api/public/v1/payments \
  -H "x-api-key: pkm_..." \
  -H "content-type: application/json" \
  -d '{"amount":25000,"reason":"Boost de boutique 7 jours",
       "redirectUri":"https://mon-site.fr/retour",
       "callbackUrl":"https://mon-site.fr/hooks/pokemania"}'

-> { "paymentId": "k7m2xqhr4tzp",
     "url": "https://www.pokemania.top/payer/k7m2xqhr4tzp" }

Tu ne peux que proposer. L'appel ne prélève rien : il fabrique un lien où le joueur lit qui demande, combien et pourquoi, avec son solde sous les yeux, et décide. Aucune application ne peut débiter un joueur sans cet écran — au-delà de 100 000, il lui en faut même deux. L'argent va sur le compte du développeur propriétaire de l'application.

Redirige le joueur vers url. Elle expire en quinze minutes : génère-la au moment où le joueur clique, pas la veille.

Le résultat te parvient par un POST signé sur ton callbackUrl (en-tête x-pokemania-signature, HMAC-SHA256 du corps brut avec pour secret le SHA-256 de ta clé), et GET /payments/:id le rend à tout moment. Ne considère jamais un paiement comme acquis sur la seule redirection du joueur.

Le motif est lu par quelqu'un qui s'apprête à payer : qu'il décrive ce qu'il achète. Une demande dont le motif ne correspond pas à ce que le joueur reçoit est un motif de suspension immédiate.

curl -X POST https://public.pokemania.top/api/public/v1/me/village/pay \
  -H "x-api-key: pkm_..." \
  -H "x-player-token: pat_..." \
  -H "content-type: application/json" \
  -d '{"target":"Sacha","amount":25000,"idempotencyKey":"payout-2026-W35-sacha"}'

Une application ne crée jamais de monnaie. Elle déplace des fonds qui existent déjà, et seulement ceux d'un village qu'un joueur consentant dirige, vers un membre de ce même village. Le plafond, c'est la trésorerie — c'est ce qui permet d'ouvrir cet accès sans négocier un quota d'argent au cas par cas.

idempotencyKey est obligatoire, et c'est pour te protéger : un versement ne se défait pas. Si ta requête part deux fois, la deuxième retrouve la première et rend le même résultat avec replayed: true. Choisis une clé qui décrit le versement — un identifiant de commande, un couple (semaine, joueur) — pas un aléatoire, qui ne protège de rien.

Un refus métier (pas chef, trésorerie insuffisante, bénéficiaire hors village) reste un 200 avec paid: false et une reason à montrer au chef. Le bénéficiaire, lui, est prévenu deux fois : une ligne dans son historique bancaire nommant ton application, et une notification en jeu s'il est connecté.

curl -X POST https://public.pokemania.top/api/public/v1/me/notify \
  -H "x-api-key: pkm_..." \
  -H "x-player-token: pat_..." \
  -H "content-type: application/json" \
  -d '{"title":"Échange accepté","message":"Ton offre a été acceptée."}'

La notification porte toujours le nom et le logo de ton application, relus par le serveur depuis ta clé : tu ne les envoies pas, et tu ne peux donc pas signer du nom d'un autre. Change ton logo dans ton espace, et tes notifications changent avec lui.

Le joueur doit être connecté : rien n'est mis en file d'attente. S'il est hors ligne ou qu'il a coupé les notifications d'applications, l'appel répond quand même 200 avec delivered: false et une reason — il n'y a rien à réessayer. Limite : 5 notifications par minute et par joueur.

Notifie ce que le joueur a demandé ou provoqué. Une notification publicitaire, répétée ou sans rapport avec une action de sa part est un motif de suspension : le contenu envoyé est journalisé avec le nom de ton application en face.