SMS-API testen ohne Versand: Testschlüssel und Webhooks
So testen Sie eine SMS-Integration, ohne eine SMS zu senden: Test-API-Schlüssel, simulierte Zustellberichte für Fehler und Ablauf, signierte Test-Webhooks.
Legen Sie im TopSMS-Dashboard einen Test-API-Schlüssel an. Er nimmt dieselben Anfragen an und liefert dieselben Antworten wie ein Live-Schlüssel, sendet und berechnet aber nichts. Nach 2 bis 4 Sekunden erhält die Nachricht einen simulierten Zustellbericht: Nummern mit der Endung 0000 schlagen fehl, 0001 laufen ab, alle anderen werden zugestellt, und der Bericht geht mit derselben HMAC-Signatur wie im Livebetrieb und "test": true an Ihren Webhook.
Eine SMS-Integration besteht aus mehr als dem Sendeaufruf: Fehlerbehandlung, Zustellberichte, Webhooks, Wiederholungen, Bestätigungscodes. All das mit echten Handys zu testen ist langsam, kostet Geld und füllt fremde Posteingänge. Eine Sandbox erlaubt, den gesamten Ablauf ohne Versand zu prüfen. Diese Anleitung zeigt, wie Testschlüssel bei TopSMS funktionieren und wie Sie sie in Entwicklung und CI einsetzen.
Live-Schlüssel, Testschlüssel: der Unterschied
Setzen Sie beim Anlegen eines API-Schlüssels im Dashboard das Häkchen bei Testschlüssel. Der Schlüssel funktioniert mit denselben Endpoints und derselben Basis-URL; es gibt keinen separaten Sandbox-Host, den Sie später umstellen müssten.
| Live-Schlüssel | Testschlüssel | |
|---|---|---|
| Prüfung der Anfrage | ja | ja, identisch |
| SMS ans Netz übergeben | ja | nein |
| Guthaben belastet | ja | nein; price zeigt, was es kosten würde |
| Zustellbericht | vom Netzbetreiber | simuliert nach 2 bis 4 Sekunden |
| Webhook | signiert | signiert, mit "test": true |
| Statusabfrage | /api/sms/status/{id} | derselbe Endpoint |
Der Testschlüssel funktioniert auch beim Massenversand, mit der Verify API, der HTTP-GET-API und E-Mail zu SMS. So testen Sie jeden Einstiegspunkt.
Schritt 1: mit dem Testschlüssel senden
# delivered after 2-4 s
curl -X POST https://www.topsms.cz/api/sms/send \
-H "Authorization: Bearer TEST_CLIENT_ID:TEST_SECRET" \
-H "Content-Type: application/json" \
-d '{"to":"+4915112345678","text":"Test 1","from":"MyShop"}'
# simulated failure (number ends in 0000) and expiry (0001)
-d '{"to":"+4915112340000","text":"Test 2"}'
-d '{"to":"+4915112340001","text":"Test 3"}'Die Antwort hat dieselbe Form wie im Livebetrieb, ergänzt um test: true:
{ "ok": true, "test": true, "channel": "sms", "id": "cmx...", "externalId": "test-1a2b3c4d",
"to": "+4915112345678", "from": "MyShop", "smsCount": 1, "price": 0.089, "status": "sent" }Schritt 2: Zustellung, Fehler und Ablauf simulieren
Die letzten vier Ziffern der Empfängernummer bestimmen das Ergebnis:
…0000:failed, wie bei einer ungültigen Nummer (errorCode: "undelivered"),…0001:expired, wie bei einem dauerhaft ausgeschalteten Handy (errorCode: "expired"),- alles andere:
deliveredmit ZeitstempeldeliveredAt.
Der Status wechselt 2 bis 4 Sekunden nach dem Senden. Ihr Code muss also wirklich auf den asynchronen Bericht warten, statt Erfolg anzunehmen. Sie können /api/sms/status/{id} mit der id oder der externalId abfragen oder den Webhook empfangen. Schreiben Sie einen Test pro Ergebnis, damit der Nutzer „gesendet“, „nicht zugestellt“ und „Handy nicht erreichbar“ so sieht, wie Sie es vorsehen.
Schritt 3: Webhook empfangen und prüfen
Hinterlegen Sie für den Schlüssel eine Webhook-URL. Das Dashboard zeigt das Webhook-Secret des Schlüssels, das Sie später in der Schlüsselliste erneut kopieren können; speichern Sie es in Ihrer Konfiguration. Jeder Bericht trägt den Header X-TopSMS-Signature: sha256=…, einen HMAC-SHA256 des unveränderten Bodys mit diesem Secret. Ein simulierter Fehler sieht so aus:
{ "event": "sms.status", "id": "cmx...", "externalId": "test-1a2b3c4d",
"to": "+4915112340000", "from": "MyShop", "status": "failed", "price": 0, "currency": "EUR",
"deliveredAt": null, "failedAt": "2026-11-15T09:12:03.000Z",
"errorMessage": "...", "errorCode": "undelivered", "sentAt": "...", "test": true }Prüfen Sie die Signatur über den Roh-Body, bevor Sie das JSON parsen, und vergleichen Sie in konstanter Zeit. Ein Beispiel mit Node.js und Express:
import express from 'express'
import crypto from 'crypto'
const app = express()
const SECRET = process.env.TOPSMS_WEBHOOK_SECRET
app.post('/topsms/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex')
const given = req.get('X-TopSMS-Signature') || ''
const ok = given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
if (!ok) return res.sendStatus(401)
const event = JSON.parse(req.body.toString('utf8'))
if (event.test) console.log('test event', event.status)
// update the message status in your database here
res.sendStatus(200)
})Antworten Sie innerhalb von 5 Sekunden mit HTTP 2xx. Schlägt Ihr Endpoint fehl, versucht TopSMS es nach 30 Sekunden und nach 2 Minuten erneut, insgesamt dreimal. Weiterleitungen werden nicht verfolgt; geben Sie also die endgültige URL an. Gestalten Sie Ihren Handler idempotent: Derselbe Bericht kann mehrfach ankommen, wenn Ihre erste 200-Antwort verloren ging.
Schritt 4: die Schaltfläche für den Test-Webhook
Um Ihren Endpoint zu testen, müssen Sie nicht einmal eine Nachricht senden. Öffnen Sie im Dashboard unter API-Zugang beim Schlüssel Protokoll & Webhook und klicken Sie auf Test-Webhook senden. TopSMS sendet ein Beispielereignis sms.status mit "test": true, signiert mit dem Secret des Schlüssels, und zeigt den HTTP-Status Ihres Servers oder einen verständlichen Fehler: Zertifikat nicht gültig für die Domain, Verbindung abgelehnt, Zeitüberschreitung, Weiterleitung. Dasselbe Protokoll listet die letzten 100 API-Aufrufe des Schlüssels und jeden Webhook-Versuch mit der Antwort Ihres Servers, gespeichert für 30 Tage.
Schritt 5: Bestätigungscodes testen
Mit einem Testschlüssel sendet POST /api/verify/send nichts und liefert testCode zurück. Der Code besteht immer aus den ersten Ziffern von 12345678: 123456 bei den standardmäßigen sechs Stellen. Alle Limits bleiben aktiv (fünf Versuche, fünf Codes pro Stunde und Nummer, 30 Sekunden zwischen zwei Codes), sodass Sie auch Sperren und die Schaltfläche „Code erneut senden“ testen können. Danach liefert POST /api/verify/check mit dem Testcode valid: true.
Testschlüssel in CI
- Legen Sie den Testschlüssel in den CI-Secrets ab und den Live-Schlüssel nur in der Produktion. Ein Testschlüssel pro Umgebung hält die Protokolle getrennt.
- Verwenden Sie in Ihren Testdaten Nummern mit der Endung 0000 und 0001 für die Fehlerpfade.
- Für Webhook-Tests in CI ohne öffentliche URL rufen Sie Ihren Handler direkt mit einem Body auf, den Sie mit demselben HMAC selbst signieren; den echten Netzwerkweg prüfen Sie einmal über die Schaltfläche im Dashboard.
- Verwenden Sie auch in Tests einen
Idempotency-Key. So sehen Sie, dass eine wiederholte Anfrage die ursprüngliche Antwort liefert statt einer zweiten Nachricht.
Live gehen
Legen Sie einen Live-Schlüssel mit denselben Einstellungen an, tauschen Sie den Schlüssel in Ihrer Konfiguration und senden Sie eine echte SMS an Ihr eigenes Handy. Neue Konten erhalten nach Bestätigung der Telefonnummer 0,50 € Startguthaben, genug für einige Live-Tests zu 0,089 € pro SMS nach Deutschland und Österreich. Details stehen in der Dokumentation; wenn Sie bei null anfangen, lesen Sie zuerst SMS-API integrieren in 5 Minuten. Kostenloses Konto anlegen.
Häufige Fragen
Prüft ein Testschlüssel meine Anfragen überhaupt?
Ja. Nummernformat, Text, Absender, Sperrliste und die Berechtigungen des Schlüssels werden wie bei einem Live-Schlüssel geprüft, Fehler kommen mit denselben Codes zurück. Nur die Übergabe ans Netz und die Abrechnung entfallen.
Wie teste ich die Verify API?
Mit einem Testschlüssel sendet /api/verify/send nichts, und der Code besteht aus den ersten Ziffern von 12345678 (123456 bei sechs Stellen). Die Antwort enthält ihn zusätzlich als testCode, sodass automatisierte Tests ihn auslesen können.
Nutzt der Test-Webhook die echte Signatur?
Ja. Simulierte Zustellberichte und die Schaltfläche „Test-Webhook senden“ signieren den Body mit dem Webhook-Secret Ihres Schlüssels im Header X-TopSMS-Signature, genau wie Live-Berichte.
Was bedeutet das Feld price im Testmodus?
Es zeigt, was die Nachricht mit einem Live-Schlüssel gekostet hätte. Das Guthaben ändert sich nicht.