SMS-Verifizierung API: Schnellstart

Der erste ist das handler_api-Protokoll. Es ist das Anfrageformat, das Tools nutzen, die für SMS-Activate geschrieben wurden. Spricht dein Tool es, änderst du die API-Adresse und den Schlüssel und behältst deinen Code.

Der zweite ist die JSON API v2. Sie hat einfache JSON-Anfragen und -Antworten, webhooks und klare Status. Nutze sie für alles, was du von Grund auf neu schreibst.

Jede Anfrage geht an eine einzige Adresse, mit deinem Schlüssel und dem Namen einer Aktion. Die Adresse steht in der Dokumentation. Die wichtigsten Aktionen sind die, die dein Tool schon sendet.

• getNumber: eine Nummer für einen Dienst und ein Land kaufen.
• getStatus: abfragen, ob der Code angekommen ist.
• setStatus: den Zustand einer Aktivierung ändern, zum Beispiel um sie zu stornieren.
• getBalance: das Guthaben deines Guthabenkontos auslesen.

Dein Schlüssel steht auf der Entwickler-Seite deines Kontos. Sende ihn bei jeder Anfrage als Bearer-Token im Authorization-Header.

Fang mit GET /catalog an. Es gibt die Angebote zurück, die du gerade kaufen kannst, mit deinem Preis, und du kannst nach Land und nach Dienst filtern. GET /balance gibt das Guthaben in US-Dollar zurück. Das Guthabenkonto lässt sich ab 3 $ aufladen.

Der ganze Ablauf besteht aus wenigen Aufrufen.

Eine Aktivierung hat einen von vier Status: waiting, completed, expired oder cancelled. Stornieren geht nur, solange sie noch waiting ist.

Standardmäßig wartet eine Aktivierung zehn Minuten auf den Code und läuft dann ab. Du kannst beim Kaufaufruf eine kürzere oder längere Wartezeit festlegen, von zwei bis zwanzig Minuten. GET /activations listet deine Aktivierungen auf, die neuesten zuerst.

• POST /activations mit einem Dienst und einem Land kauft eine Nummer.
• GET /activations/:id gibt die Aktivierung zurück. Frag sie ab, bis der Code da ist.
• Oder gib beim Kaufaufruf eine webhook-Adresse mit, und wir rufen deinen Server auf, wenn der Code ankommt.
• POST /activations/:id/cancel storniert eine Aktivierung im Status waiting, mit voller Erstattung.

Netzwerke fallen aus, und ein Kaufaufruf mit Zeitüberschreitung ist vielleicht trotzdem durchgegangen. Sende bei POST /activations einen Idempotency-Key-Header mit. Wiederholst du den Aufruf mit demselben Schlüssel, bekommst du die erste Aktivierung zurück, keinen zweiten Kauf.

Jeder Endpunkt hat sein eigenes Rate Limit, von 30 bis 120 Anfragen pro Minute, und die Dokumentation führt jedes einzeln auf. Wenn du den webhook nutzt, musst du kaum noch abfragen. webhooks sind signiert, prüfe also die Signatur, bevor du einem vertraust.

Jede Nummer ist eine echte SIM-Karte in einem Mobilfunknetz, verkauft für eine Aktivierung eines Dienstes. Sie empfängt nur SMS, keine Anrufe. Wir versprechen nicht, dass eine App eine Nummer akzeptiert oder einen Code sendet, dein Code muss also mit Aktivierungen rechnen, die ohne einen enden.

Du zahlst nur für einen Code, der ankommt. Kommt keiner, storniere die Aktivierung oder lass sie ablaufen, und der volle Preis geht automatisch zurück auf dein Guthabenkonto. Behandle das als gewöhnlichen Zweig, nicht als Fehler.

Die meisten frühen Probleme entstehen, wenn diese Schritte übersprungen werden.

• Führe zuerst eine Aktivierung von Hand durch und lies jedes Feld der Antwort.
• Lass eine Aktivierung absichtlich ablaufen und beobachte, wie das Guthaben zurückkommt.
• Vergleiche deine Länder- und Dienstcodes mit der Dokumentation. Ein falscher Code kann eine Nummer zurückgeben, die du nicht wolltest.
• Behalte den Schlüssel auf deinem Server, nie in einer App oder auf einer Webseite.