REST API
SimplyConnect bietet eine REST API, mit der Sie Funktionen der Telefonanlage programmatisch steuern und in eigene Anwendungen integrieren können.
Hinweis: Die API ist für den Hauptbenutzer sowie für Unterbenutzer mit der Berechtigung api verfügbar.
Was kann die API?
Die SimplyConnect REST API ermöglicht unter anderem:
| Bereich | Möglichkeiten |
|---|---|
| Konten & Nebenstellen | Unterkonten abfragen und verwalten |
| Anrufdaten (CDR) | Einzelverbindungsnachweise abfragen und filtern |
| Fax | Faxe senden und empfangene Faxe abrufen |
| Anrufe auslösen | Click-to-Call -- Anrufe programmatisch starten |
| Konferenzen | Konferenzräume verwalten und Teilnehmer steuern |
| Rufnummern (DDI) | DDI-Routing und -Zuordnung abfragen und ändern |
| Vorwahlen | Vorwahlnummern und Tarifzonen abfragen |
| Registrierungsstatus | Online-Status von SIP-Geräten prüfen |
Authentifizierung
Die API unterstützt zwei Authentifizierungsverfahren:
Bearer Token (empfohlen)
Senden Sie Ihren API-Schlüssel als Bearer Token im Authorization-Header:
Authorization: Bearer IHR_API_SCHLUESSEL
Dies ist die empfohlene Methode für neue Integrationen.
Legacy HMAC-SHA1
Für die Abwärtskompatibilität wird auch die HMAC-SHA1-Signaturmethode unterstützt:
Authorization: apiKey:requestSignature
Dabei wird die Request-Signatur aus den Anfrageparametern und einem geheimen Schlüssel berechnet. Details finden Sie in der interaktiven API-Dokumentation.
API-Schlüssel erstellen
So erstellen Sie einen API-Schlüssel:
- Navigieren Sie zu Entwickler > API-Schlüssel (
/entwickler/api-schlüssel). - Klicken Sie auf Neuen Schlüssel erstellen.
- Vergeben Sie eine Bezeichnung für den Schlüssel (z.B. "CRM-Integration", "Monitoring-Script").
- Der Schlüssel wird angezeigt. Kopieren und speichern Sie ihn sicher -- er wird nur einmal vollständig angezeigt.
Tipp: Erstellen Sie für jede Anwendung oder Integration einen eigenen API-Schlüssel. So können Sie einzelne Schlüssel widerrufen, ohne andere Integrationen zu beeinträchtigen.
Rate Limiting
Die API ist auf 60 Anfragen pro Minute begrenzt (pro authentifiziertem Benutzer). Bei Überschreitung erhalten Sie den HTTP-Status 429 Too Many Requests. Warten Sie in diesem Fall kurz, bevor Sie weitere Anfragen senden.
Die verbleibenden Anfragen und das Reset-Intervall werden in den Response-Headern mitgeteilt:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Interaktive API-Dokumentation
Die vollständige, interaktive API-Dokumentation mit allen Endpunkten, Parametern, Beispielanfragen und -antworten finden Sie unter:
Dort können Sie Anfragen direkt im Browser testen und die verfügbaren Endpunkte erkunden.
Schnellstart-Beispiel
Ein einfaches Beispiel zum Abrufen Ihrer Kontodaten mit curl:
curl -H "Authorization: Bearer IHR_API_SCHLUESSEL" \
https://my.simply-connect.net/api/v1/accounts
Die API antwortet mit JSON. Alle Endpunkte folgen dem Schema /api/v1/{ressource}.
Häufige Fragen
Ich erhalte den Fehler 401 Unauthorized -- was tun?
Prüfen Sie, ob Ihr API-Schlüssel korrekt ist und im Authorization-Header übermittelt wird. Stellen Sie sicher, dass Ihr Benutzer die API-Berechtigung besitzt.
Kann ich mit der API Anrufe tätigen?
Ja. Über den Endpunkt zur Anrufinitiierung können Sie Click-to-Call-Funktionalität in Ihre Anwendung integrieren. Details finden Sie in der API-Dokumentation.