Automatiser la vérification par SMS : le guide complet de l'API

Le site web convient très bien pour une inscription occasionnelle : quelques clics, une courte attente pour un SMS. Il ne suffit plus quand vous écrivez des tests automatisés, un script d'inscription en masse, un pipeline CI, ou un bot qui doit récupérer un code de vérification sans supervision. Le site web ne peut pas faire ça. L'API, si. Voici tout ce qu'il faut savoir pour partir de zéro et obtenir un flux qui fonctionne.

Étape 1 : obtenez une clé API

Connectez-vous et allez sur /account/api-keys pour en créer une. Les clés se présentent sous la forme jm_ suivi d'une chaîne aléatoire. Le texte en clair n'est affiché qu'une seule fois — nous stockons un hash, pas la clé elle-même, donc il n'existe aucune option pour « récupérer ma clé » si vous la perdez. Il ne reste qu'à la supprimer et à en créer une nouvelle.

Chaque requête utilise l'authentification Bearer standard :

Authorization: Bearer jm_your_key

Traitez cette clé comme un mot de passe — ne la commitez pas dans un dépôt public, ne la collez pas dans une conversation pour que quelqu'un d'autre vous aide à déboguer. Si vous pensez qu'elle a fuité, retournez sur /account/api-keys, supprimez-la et générez-en une nouvelle ; l'ancienne cesse de fonctionner immédiatement.

Étape 2 : choisissez un service et un pays

Passer une commande nécessite deux éléments : service (un code de service) et country (un identifiant de pays). Commencez par lister le catalogue :

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

Chaque élément a un champ code (celui de Telegram est tg) — transmettez-le directement à l'endpoint de commande, c'est plus fiable que de reconstruire un slug vous-même. Pour voir le prix et le stock en temps réel d'un service donné dans tous les pays, ajoutez le paramètre service :

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

Chaque entrée de items contient countryId / priceCents / count (le nombre de numéros disponibles actuellement). Vérifiez count avant de commander — s'il est à zéro, la commande échouera à coup sûr, alors ne gaspillez pas un appel pour le découvrir à vos dépens.

Étape 3 : passez la commande

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

Une commande réussie renvoie un numéro de téléphone et une date d'expiration :

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

Le débit a lieu à cette étape — chargedCents est le montant réellement prélevé (en centimes). Confiez ce numéro à l'application cible pour recevoir le code de vérification, puis passez à l'étape suivante.

Étape 4 : interrogez l'API jusqu'à obtenir le code

Il n'y a ni WebSocket ni webhook — vous récupérez le contenu du SMS en interrogeant GET /api/v1/orders/:id jusqu'à ce que smsBody ne soit plus null :

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

Cinq secondes constituent un bon point de départ — le numéro reste valable 15 minutes, et la limite de 60 requêtes par minute pour les lectures laisse une large marge. Trois secondes fonctionnent aussi si vous êtes impatient ; interroger l'API toutes les secondes ne fait pas arriver le code plus vite, cela ne fait que consommer votre quota plus rapidement.

Pièges

• Les limites de débit sont par utilisateur, pas par clé. Les endpoints d'écriture (order / cancel / next-sms) sont limités à 10 par minute par utilisateur ; les lectures, à 60 par minute. Créer des clés supplémentaires ne relève pas votre plafond — elles partagent toutes le même.
• Les numéros expirent après 15 minutes. Un numéro inutilisé qui expire sans avoir reçu de code est remboursé automatiquement — inutile de le demander. Mais si votre propre pipeline met trop de temps à réellement utiliser le numéro (coincé dans une file d'attente, par exemple), il sera déjà mort à votre tour.
• Un numéro peut recevoir plusieurs codes. Si l'application cible envoie le SMS en deux temps (une confirmation d'inscription, puis un code de connexion distinct), appelez POST /api/v1/orders/:id/next-sms dès l'arrivée du premier pour nous dire « j'ai terminé avec celui-ci, continuez à écouter » — sans avoir besoin de passer une nouvelle commande pour obtenir un autre numéro.
• Une fois qu'un code est arrivé, l'annulation ne fonctionne plus. POST /api/v1/orders/:id/cancel rembourse instantanément tant que le numéro est encore en attente d'un code. Une fois que smsBody a été non nul, le même appel renvoie plutôt une erreur CODE_RECEIVED — vous avez déjà obtenu ce que vous avez payé, impossible de faire machine arrière.
• Ne vérifiez pas le status une seule fois avant d'abandonner. Le status passe de WAITING à RECEIVED. S'il reste bloqué sur WAITING jusqu'à l'expiration, c'est généralement un problème de taux de livraison propre à cette combinaison pays/service — passer une nouvelle commande dans un autre pays résout généralement le problème plus vite que d'attendre.

Pour aller plus loin

Cela couvre le flux principal, de la commande au code. La liste complète des champs, les codes d'erreur et les cas particuliers de chaque endpoint se trouvent sur /api-docs. Si vous faites tourner cela à grande échelle — en maintenant par exemple les flux de vérification de dizaines de comptes en parallèle — chronométrez le polling de chaque commande indépendamment. Ne les mettez pas en file dans une seule boucle séquentielle, sinon les numéros les plus anciens expireront pendant que vous attendez encore le premier.