API de vérification SMS : démarrage rapide

La première est le protocole handler_api. C’est le format de requête qu’utilisent les outils écrits pour SMS-Activate. Si votre outil le parle, vous changez l’adresse de l’API et la clé, et vous gardez votre code.

La seconde est l’API JSON v2. Elle a des requêtes et des réponses en JSON simple, des webhooks et des statuts clairs. Utilisez-la pour tout ce que vous écrivez de zéro.

Chaque requête part vers une seule adresse, avec votre clé et un nom d’action. L’adresse est dans la documentation. Les actions principales sont celles que votre outil envoie déjà.

• getNumber : acheter un numéro pour un service et un pays.
• getStatus : demander si le code est arrivé.
• setStatus : changer l’état d’une activation, par exemple pour l’annuler.
• getBalance : lire le solde de votre portefeuille.

Votre clé se trouve sur la page Développeurs de votre compte. Envoyez-la comme jeton Bearer dans l’en-tête Authorization de chaque requête.

Commencez par GET /catalog. Il renvoie les offres que vous pouvez acheter en ce moment, avec votre prix, et vous pouvez le filtrer par pays et par service. GET /balance renvoie le solde du portefeuille en dollars américains. Le portefeuille se recharge à partir de 3 $.

Tout le parcours tient en quelques appels.

Une activation a l’un de ces quatre statuts : waiting, completed, expired ou cancelled. L’annulation n’est possible que tant qu’elle est encore en waiting.

Par défaut, une activation attend le code dix minutes, puis expire. Vous pouvez fixer une attente plus courte ou plus longue dans l’appel d’achat, de deux à vingt minutes. GET /activations liste vos activations, de la plus récente à la plus ancienne.

• POST /activations avec un service et un pays achète un numéro.
• GET /activations/:id renvoie l’activation. Interrogez-le jusqu’à ce que le code soit là.
• Ou bien passez une adresse de webhook dans l’appel d’achat, et nous appelons votre serveur quand le code arrive.
• POST /activations/:id/cancel annule une activation en waiting, pour un remboursement complet.

Les réseaux tombent en panne, et un appel d’achat qui a expiré est peut-être passé quand même. Envoyez un en-tête Idempotency-Key sur POST /activations. Si vous réessayez avec la même clé, vous récupérez la première activation, pas un deuxième achat.

Chaque point d’accès a sa propre limite de débit, de 30 à 120 requêtes par minute, et la documentation les liste toutes. Si vous utilisez le webhook, vous n’avez presque plus besoin d’interroger l’API. Les webhooks sont signés, alors vérifiez la signature avant de vous y fier.

Chaque numéro est une vraie carte SIM sur un réseau mobile, vendue pour une activation d’un seul service. Il reçoit uniquement des SMS, pas des appels. Nous ne promettons pas qu’une appli acceptera un numéro ou enverra un code, donc votre code doit prévoir des activations qui se terminent sans code.

Vous payez uniquement un code reçu. Quand aucun ne vient, annulez l’activation ou laissez-la expirer, et le prix complet revient automatiquement sur votre portefeuille. Gérez cela comme une branche ordinaire, pas comme une erreur.

La plupart des problèmes du début viennent du fait d’avoir sauté ces étapes.

• Lancez d’abord une activation à la main, et lisez chaque champ de la réponse.
• Laissez exprès une activation expirer, et regardez le solde revenir.
• Vérifiez vos codes de pays et de service dans la documentation. Un mauvais code peut renvoyer un numéro que vous ne vouliez pas.
• Gardez la clé sur votre serveur, jamais dans une appli ni dans une page web.