SMS-Verifizierung per API automatisieren: ein Leitfaden für Entwickler

Mit der REST-API von SMS Activate App kauft dein Code eine private Nummer, startet die Verifizierung und liest den SMS-Code für eigene Apps, Konten und Tests.

Dieser Leitfaden zeigt den ganzen Ablauf: eine Nummer auswählen, sie sicher kaufen, den OTP-Code (Einmalpasswort) auslesen und die Nummer freigeben, wenn du fertig bist.

Wann sich Automatisierung lohnt

Automatisierung passt zu Abläufen, die dir gehören und die du wiederholst. Drei typische Fälle:

  • End-to-End-Tests der SMS-Schritte in deiner eigenen App: Registrierung, Login, Passwort-Reset und 2FA (Zwei-Faktor-Authentifizierung).
  • 2FA für deine eigenen Dienstkonten und internen Tools funktionsfähig halten.
  • Ein Verifizierungsschritt in einem Produkt, das du betreibst.

Jede Nummer ist eine private virtuelle Nummer. Je nach Land ist sie eine echte Mobil- oder Ortsnummer aus dem Nummernbereich eines Netzbetreibers. Dein Konto hält sie für eine Laufzeit von 28 Tagen. Dieselbe Nummer empfängt auch spätere Codes, damit funktionieren erneute Verifizierung und Kontowiederherstellung während der Laufzeit weiter.

Dabei gelten zwei Grenzen. Eine Nummer ist nach der Vergabe endgültig und wird nicht erstattet. Ob eine Plattform eine Nummer akzeptiert, entscheidet die Plattform, bei der du dich verifizierst, nicht wir.

Die meisten Codes kommen innerhalb weniger Minuten an, nachdem die Plattform sie verschickt hat. Eine Zustellrate veröffentlichen wir noch nicht. Prüfe eine Nummer deshalb mit deiner Zielplattform, bevor du eine Pipeline darauf aufbaust.

Die API empfängt SMS. Senden kann sie keine.

Bevor du loslegst

  • Lege auf der Registrierungsseite ein kostenloses Konto an.
  • Lade Guthaben auf das Konto.
  • Erstelle im Konto-Dashboard auf dem Tab „API-Schlüssel“ oder im Telegram-Bot einen persönlichen API-Schlüssel.

Sende den Schlüssel bei jeder Anfrage mit, auch beim Katalog:

Mit dem Schlüssel wird dein Guthaben ausgegeben. Bewahre ihn serverseitig auf, in einem Secret Store oder als CI-Secret. Schreib ihn nie in Client-Code und committe ihn nie in ein Repository.

Referenzangaben:

  • Basis-URL: https://api.sms-activate.app/v1/public
  • Beträge sind ganzzahlige US-Cent. balanceCents: 2000 bedeutet 20,00 $.
  • Maschinenlesbare Spezifikation: die OpenAPI-Datei (OpenAPI 3.1).
  • Dokumentation zum Lesen: die API-Dokumentation.
  • Ein fertiger Skill für LLM-Agenten: der Agenten-Skill.
  • Limits: mindestens 120 Anfragen pro Minute und Konto sowie 30 Käufe pro Minute. Wer darüber liegt, bekommt rate_limited mit einem Header Retry-After.

Der Verifizierungsablauf

  • Rufe GET /countries auf. Der Endpunkt liefert für jedes Land die Verfügbarkeit und die Preisspanne.
  • Rufe GET /numbers/search?country=US&limit=1 auf, um eine verfügbare Nummer auszuwählen. Jedes Ergebnis enthält phoneNumber und deinen Preis in priceCents.
  • Kaufe die Nummer mit POST /numbers und dem Body {"phone": "<phoneNumber>", "country": "US"}. Füge einen Header Idempotency-Key: <uuid> hinzu, damit ein erneuter Versuch dich nie doppelt belastet. Ein erfolgreicher Kauf liefert 201 mit number, chargedCents und balanceAfterCents. Zwei optionale Felder stehen zur Verfügung: autoRenew (Standard true) und note.
  • Gib die Nummer in dem Ablauf ein, den du testest, und löse die SMS aus.
  • Lies den Code aus. Frage GET /numbers/{id}/sms für diese Nummer ab, oder GET /sms für alle, etwa alle 5 bis 15 Sekunden, und setze ein Timeout. Jede SMS hat id, numberId, from, to, body und receivedAt; den Code entnimmst du body. Die Feeds sind per Cursor paginiert, mit cursor, limit und nextCursor.
  • Abschließen. Sende PATCH /numbers/{id} mit {"autoRenew": false}, um die Verlängerung zu stoppen, oder DELETE /numbers/{id}, um die Nummer freizugeben. Für eine Testsuite, die du täglich ausführst, ist es meist einfacher, eine Nummer in der Verlängerung zu behalten, statt bei jedem Lauf eine neue zu kaufen.

Beispiel mit curl

Der erste Aufruf findet eine Nummer. Der zweite kauft sie. Der dritte liest eingehende SMS.

Ersetze +15551234567 durch eine Nummer, die der erste Aufruf zurückgegeben hat. Wenn du den Kauf nach einem Netzwerkfehler wiederholst, verwende denselben Wert für Idempotency-Key, statt einen neuen zu erzeugen.

Beispiel in Python

Diese Funktion wartet auf einen Code für eine Nummer, die du bereits besitzt. Die Funktion nutzt die Bibliothek requests und liest den Schlüssel aus der Umgebung.

Wenn ältere SMS auf derselben Nummer passen könnten, vergleiche receivedAt mit dem Zeitpunkt, zu dem dein Test die Nachricht ausgelöst hat. Nimm dann nur eine neuere.

Webhook statt Polling

Sende PATCH /numbers/{id} mit {"forwardWebhookUrl": "https://your-app.example.com/sms"}, und jede SMS und jeder Anruf auf dieser Nummer wird sofort bei Eingang an deinen Server gesendet. Die Adresse wird vorher geprüft und muss einen POST zum Test mit einem 2xx-Status beantworten.

Jede Anfrage trägt x-vpn-event, x-vpn-timestamp und x-vpn-signature. Die Signatur ist HMAC-SHA256 über v1.<timestamp>.<raw body> mit deinem Webhook-Secret. Prüfe sie anhand der rohen Bytes und lehne einen Zeitstempel ab, der um mehr als fünf Minuten abweicht.

Für einen Test, der einmal läuft, ist Polling einfacher. Ein Webhook passt zu einem dauerhaft laufenden Dienst, der Codes verarbeitet, sobald sie eingehen.

Fehler als Antworten behandeln

Jeder Fehler hat dieselbe Form:

Verzweige anhand des error-Codes, nie anhand des HTTP-Status. Ein Status kann für mehr als eine Ablehnung stehen, deshalb verrät dir der Status allein nicht, was passiert ist. Manche Ablehnungen enthalten zusätzlich ein Objekt details, zum Beispiel requiredCents und availableCents bei insufficient_balance.

Codes, die du behandeln solltest:

  • insufficient_balance: Dein Guthaben deckt den Kauf nicht. Brich ab und lade Guthaben auf.
  • no_numbers: Gerade ist keine passende Nummer verfügbar. Wähle eine andere Nummer oder ein anderes Land.
  • number_unavailable: Die Nummer wurde verkauft oder ist nicht mehr im Angebot. Suche erneut.
  • validation_failed: Request-Body oder Parameter sind fehlerhaft, oder dem Kauf fehlt der Idempotency-Key. Korrigiere die Eingabe.
  • idempotent_replay: Eine Anfrage mit diesem Idempotency-Key kam mit einem anderen Body oder wird noch verarbeitet. Behandle sie nicht als neuen Kauf.
  • rate_limited: Zu viele Anfragen. Warte so lange, wie der Header Retry-After angibt.
  • priceexceeded und providerfailure: Lies message, zeige die Meldung an und beende den Lauf. Prüfe nach provider_failure deine Nummern, bevor du erneut kaufst.

Keiner dieser Fehler ist ein Defekt, den du blind wiederholen solltest. Zeige den Fehler der Person, die den Code ausführt, oder beende den Lauf. Bewahre die reqId in deinen Logs auf. Der Support findet damit deine Anfrage.

In einer CI-Testsuite

  • Führe SMS-Tests als eigenen, seriellen Job aus, damit nie zwei Tests denselben Code lesen.
  • Speichere den API-Schlüssel als CI-Secret.
  • Ordne jeden Code seinem Test über die Nummer und die Startzeit des Tests zu.
  • Setze ein Timeout und lass den Test mit einer klaren Meldung fehlschlagen, die Nummer und Schritt nennt.
  • Behalte für wiederholte Läufe eine Nummer, die sich verlängert, statt jedes Mal eine neue zu kaufen.

Nützliche Videos

Videos von Dritten zu den Techniken, die diese Anleitung verwendet. Die Videos vermitteln allgemeine Techniken und behandeln unseren Dienst nicht.

Nächste Schritte