Une seule API pour les commandes, le portefeuille et la marketplace

Un seul contrat, versionné par date

Chaque point de terminaison se trouve sous /v1 sur le domaine de la boutique avec laquelle vous intégrez. Les réponses sont en JSON, les montants sont des chaînes décimales associées à une devise ISO 4217, et les horodatages sont au format ISO 8601. Chaque réponse porte un en-tête X-Api-Version avec la date du contrat avec lequel vous communiquez, et un X-Request-Id que vous pouvez citer à l’assistance. Les erreurs ont toujours le même corps : un objet d’erreur avec un code stable, un message lisible et des détails facultatifs, ainsi que le request_id.

Le fichier OpenAPI 3.1 décrit chaque chemin, chaque schéma et chaque code d’erreur. Importez-le dans votre client HTTP ou votre générateur et vous obtenez des requêtes typées pour le catalogue, les commandes, le portefeuille, les annonces, les offres et les remises de transactions.

Clés, autorisations et le compte qu’elles représentent

Une clé est créée par le titulaire du compte sur l’offre Revendeur et n’est affichée qu’une fois ; seule une empreinte est conservée. Lors de la création, vous choisissez ses autorisations, une liste blanche d’IP facultative (jusqu’à 20 adresses) et une expiration facultative. La rotation crée une nouvelle clé avec les mêmes autorisations et révoque l’ancienne, ce qui permet de renouveler les identifiants sans interruption. Les commandes passées avec une clé sont débitées du portefeuille du compte et apparaissent dans le même tableau de bord que les commandes manuelles, avec leur source marquée comme API.

Chaque clé hérite de la limite de requêtes par minute du niveau de client du compte. Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset indiquent où vous en êtes ; au-delà de la limite, l’API renvoie 429 avec un en-tête Retry-After, et la bonne réaction est d’attendre exactement ce délai.

Écritures idempotentes et lots

La création de commande est le seul appel qui déplace de l’argent, elle est donc protégée deux fois. D’abord, l’en-tête Idempotency-Key est obligatoire : répéter une requête avec la même clé renvoie la commande d’origine sans second débit, et réutiliser la clé avec un corps différent est refusé avec 409 IDEMPOTENCY_KEY_REUSE. Ensuite, une fenêtre de doublons détecte le même service, le même lien et la même quantité renvoyés dans un court intervalle sans correspondance de clé, et renvoie 409 DUPLICATE_ORDER.

Les lots acceptent jusqu’à 100 commandes par appel. Chaque élément est validé et débité séparément, identifié par la clé du lot et son index, et la réponse liste un résultat par élément, si bien qu’une ligne défectueuse ne bloque jamais les autres. Utilisez d’abord POST /v1/orders/preview lorsque vous voulez le montant exact et le résultat de validation sans rien créer.

• Générez un UUID par commande logique et enregistrez-le avant l’envoi.
• En cas d’expiration, renvoyez avec la même clé ; ne générez jamais une nouvelle clé pour la même commande.
• Considérez les codes 4xx comme définitifs, et les codes 5xx et 429 comme réessayables avec un délai croissant.

Des webhooks auxquels vous pouvez faire confiance

Chaque changement d’état est écrit dans une file d’attente, dans la même transaction de base de données que le changement lui-même, et un distributeur le livre à votre point de terminaison https avec trois en-têtes : Webhook-Id, Webhook-Timestamp et Webhook-Signature. La signature est un HMAC-SHA256 de l’horodatage, d’un point et du corps brut, calculé avec le secret du point de terminaison affiché une seule fois à la création. Vérifiez-la en temps constant, rejetez les horodatages de plus de cinq minutes et dédoublonnez par Webhook-Id, car un événement réessayé porte le même identifiant.

Les envois qui ne reçoivent pas de 2xx sont réessayés après 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 12 heures et 24 heures avant d’être marqués comme définitivement en échec. Répondez vite et traitez de façon asynchrone ; un gestionnaire lent est la cause la plus fréquente de traitement en double.

Panneaux enfants par le point de terminaison SMM v2

Si votre panneau parle déjà le format répandu « SMM API v2 », vous pouvez ajouter cette boutique comme fournisseur en collant l’URL /api/v2 et votre clé. Les actions services, add, status, balance, refill, refill_status et cancel sont prises en charge, les prix reviennent dans la devise et le niveau de votre compte, et les erreurs utilisent la forme plate { "error": "message" } attendue par ces panneaux. L’idempotence est dérivée du contenu de la commande et de la minute en cours, si bien que les doubles envois accidentels dans la même minute sont fusionnés.