Démarrage rapide de l'API pour développeurs

L'API pour développeurs de SmsGrab donne à votre logiciel les mêmes numéros que l'application, via une API REST en JSON. C'est un produit payant avec ses propres tarifs développeurs, réglé avec votre solde SmsGrab habituel et couvert par les mêmes remboursements automatiques.

Qui peut l'utiliser

• Un compte e-mail dont l'adresse est confirmée. Les comptes invités ne peuvent pas créer de clés.
• Un compte sans restriction.

1. Créer une clé API

Ouvrez Compte > Développeurs sur le site, ou Paramètres > API développeur dans l'application, et créez une clé. Par sécurité, vous confirmez avec votre mot de passe, et avec votre code de validation en deux étapes s'il est activé. Choisissez la portée read pour les outils en lecture seule, ou read et purchase pour acheter des numéros.

La clé commence par sgk_ et ne s'affiche qu'une seule fois. Conservez-la dans le coffre à secrets de votre serveur. Voir Clés API et sécurité.

2. S'authentifier

L'URL de base est https://smsgrab.com/api/dev/v1. Envoyez la clé comme jeton Bearer ou dans l'en-tête X-Api-Key :

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Les clés restent sur les serveurs. Ne les placez jamais dans un site Web, une extension de navigateur ou une application distribuée à d'autres personnes.

3. Consulter votre solde et les prix

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Les montants sont toujours exprimés en unités mineures d'USD : 18 signifie 0,18 USD. price_minor est votre prix développeur, retail_price_minor le prix de l'application.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Acheter un numéro

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service et country prennent nos identifiants, comme whatsapp et indonesia. Pour les pays, les codes ISO comme ID fonctionnent aussi.
• max_price_minor vous protège : si le prix a augmenté, rien n'est débité et vous recevez 409 PRICE_CHANGED.
• Idempotency-Key sécurise les nouvelles tentatives. La même requête avec la même clé renvoie le premier résultat au lieu d'acheter deux fois.

La réponse est 201 Created avec l'activation :

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. Attendre le SMS

Plutôt que d'interroger l'API en boucle, laissez-la retenir la requête jusqu'à un changement, pendant 30 secondes au maximum :

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Quand un message arrive, status passe à CODE_RECEIVED et sms contient tous les messages reçus :

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Vous préférez être notifié plutôt qu'interroger ? Configurez des webhooks.

6. Terminer ou annuler

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish une fois le code utilisé. Accepté uniquement après l'arrivée d'un code.
• cancel tant que vous attendez encore le premier code. Le prix complet est remboursé.
• Si vous ne faites rien, un numéro sans code expire au bout de 20 minutes et il est remboursé automatiquement.

Valeurs de statut

Erreurs

Toutes les erreurs ont la même forme. Réagissez selon code et reason, et ignorez les motifs que vous ne connaissez pas encore :

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Les cas courants sont 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 avec ACTIVATION_LIMIT_REACHED (100 numéros au plus peuvent attendre en même temps par compte) et 429 RATE_LIMITED avec un en-tête Retry-After.

La référence complète se trouve dans la documentation pour développeurs.