Documentation de l'API revendeur

L'API revendeur SHOP2TOPUP est une API REST JSON pour vendre des recharges de jeux et des codes de cartes cadeaux depuis votre propre boutique, votre site ou votre bot. Cette référence documente chaque endpoint public, ses paramètres et ses réponses.

URL de base et transport

Tous les chemins de cette référence sont relatifs à l'URL de base ci-dessous. Requêtes et réponses sont en JSON sur HTTPS, les montants sont des chaînes de caractères pour qu'aucun arrondi flottant ne s'y glisse, et chaque horodatage est en UTC au format ISO 8601.

https://shop2topup.com/api/endpoints/v1

Authentification

Chaque requête porte un seul en-tête. La paire de clés est délivrée depuis la page API Access de votre panneau revendeur et peut être restreinte à une liste d'IP autorisées ; un appel venant de toute autre adresse est rejeté avec IP_NOT_ALLOWED avant d'atteindre la moindre logique métier.

En-tête de requête

Authorization: Bearer <keyId>.<secret>

Un premier appel

Rien à installer. Insérez votre propre clé et cet appel renvoie des données de catalogue en direct.

Requête - cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Conventions de réponse

Chaque réponse porte un champ booléen success : une seule condition sépare le cas nominal de tous les échecs.
Les échecs renvoient un objet error avec un code stable, un message lisible et des détails facultatifs. Branchez-vous sur le code, jamais sur le message.
Les montants sont toujours des chaînes décimales, par exemple "0.950000" en USD. Ne les convertissez pas en flottant binaire avant de les comparer ou de les additionner.
Les endpoints de liste renvoient un objet pagination avec page, limit, total et total_pages.
La création de commande est idempotente sur l'UUID order_id que vous fournissez : une relance ne peut donc jamais débiter deux fois.

Réponse d'erreur

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Sections de la référence

CatalogueLe catalogue est une arborescence à trois niveaux : les grandes catégories contiennent des catégories, les catégories contiennent des sous-catégories, et une sous-catégorie est l'article que vous achetez réellement. Ces endpoints vous permettent de recopier cette arborescence dans votre propre base de données et de tarifer un article juste avant de le commander.Validation joueurLa validation joueur résout un compte in-game avant tout mouvement d'argent. Elle confirme que l'identifiant existe pour ce produit, renvoie le nom in-game pour que votre acheteur puisse le vérifier, et expose la région afin qu'une commande inter-régions soit rejetée tôt plutôt que d'échouer après paiement.CommandesLes commandes sont créées avec un UUID que vous générez. Cet UUID est la clé d'idempotence : le rejouer renvoie la commande d'origine au lieu de débiter deux fois. Le statut se relit ensuite commande par commande, par lots de cinquante au maximum, ou sous forme de liste paginée.Compte et authentificationChaque requête porte un seul en-tête. GET /account est l'endpoint que vous appelez pour prouver qu'une clé fonctionne, lire le solde du portefeuille sur lequel vos commandes sont débitées, et confirmer que le compte est actif avant de lancer un traitement par lots.Codes d'erreurChaque échec renvoie un code stable, lisible par une machine, à côté du statut HTTP. Branchez-vous sur le code, jamais sur le texte du message : les messages sont écrits pour des humains et peuvent être reformulés, tandis que les codes font partie du contrat.

Limites de débit

Les limites s'appliquent par compte sur une fenêtre glissante. Les endpoints catalogue, commandes et compte portent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, et un appel limité répond 429 avec un en-tête Retry-After. La validation de joueur relève plutôt de votre quota quotidien de vérifications : elle n'envoie aucun en-tête X-RateLimit et rapporte le quota dans le corps du 429.

Route	Requêtes	Fenêtre	Comptées par
GET /catalog/* (les cinq)	5000	60 s	par compte
POST /orders/create	5000	60 s	par compte
GET /orders/:orderId	3	60 s	par compte + ID de commande
POST /orders/batch	2	60 s	par compte
GET /orders	2	60 s	par compte
GET /account	60	60 s	par compte
POST /player/validate	quota quotidien de vérifications joueur	24 h	par compte (sans en-têtes X-RateLimit)

Webhooks

Les résultats des commandes sont poussés vers un endpoint HTTPS que vous enregistrez, signés en HMAC-SHA256 sur le corps brut. La liste des événements, celle des en-têtes, la forme de la charge utile et un extrait de vérification sont documentés sur la page de présentation de l'API.

Lire la référence charge utile et signature des webhooks

Nouveau sur la plateforme ? Commencez par la présentation de l'API de recharge de jeux pour revendeurs, ou lisez la présentation du programme revendeur SHOP2TOPUP pour comprendre le fonctionnement du compte partenaire.