3CX Konfigurations-API

Was ist die Konfigurations-API?

Die 3CX Configuration API (XAPI), die in 3CX Version 20 eingeführt wurde, bietet eine REST-basierte Schnittstelle, die eine programmgesteuerte Kontrolle über nahezu jeden Konfigurationsaspekt innerhalb des 3CX-Telefonsystems ermöglicht und Funktionen repliziert, auf die normalerweise über die Administratorkonsole zugegriffen wird. Diese API basiert auf OData-Standards und OpenAPI-Spezifikationen und ermöglicht Entwicklern eine effiziente Integration, Automatisierung und Anpassung der 3CX-Umgebung.

Hauptfunktionen der Konfigurations-API

  • Umfassende Verwaltung: Mit Endpunkten zur Verwaltung von Abteilungen, Benutzern, Anrufweiterleitung, Systemnebenstellen und anderen Konfigurationen ermöglicht die API Nutzern, nahezu alle Verwaltungsaktionen programmgesteuert auszuführen. Von der Überprüfung, ob eine Abteilung vorhanden ist, bis zur Konfiguration gemeinsam genutzter Parkplätze kann nahezu jedes Element von 3CX über Code verwaltet werden.
  • Automatisierung: Die API ermöglicht die Automatisierung gängiger Verwaltungsaufgaben wie das Erstellen von Abteilungen, das Zuweisen von Benutzerrollen und das Verwalten von Nebenstellen. Dies reduziert den Bedarf an manuellen Eingriffen in die Administratorkonsole, spart Zeit und minimiert die Fehlerwahrscheinlichkeit.
  • Integration: Die API erleichtert die nahtlose Integration des 3CX-Telefonsystems in andere Geschäftsanwendungen. Sie können damit Benutzerdaten synchronisieren, Abteilungen verwalten und die Anrufweiterleitung konfigurieren, um eine reibungslose Interoperabilität zwischen 3CX und externen Diensten sicherzustellen. Die Integration von 3CX in umfassendere Arbeitsabläufe verbessert die Kommunikation und Produktivität, ohne dass eine manuelle Synchronisierung erforderlich ist.
  • Skalierbarkeit: Die API wurde mit Blick auf Skalierbarkeit entwickelt und ermöglicht eine effiziente Verwaltung von Konfigurationen bei wachsenden Unternehmen. So ist eine einfache Erweiterung von Nutzern, Abteilungen und anderen Einheiten ohne überwältigenden Verwaltungsaufwand möglich.

Konfigurieren der API-Integration

Gehen Sie in der Admin-Konsole im 3CX-Webclient zu Integrationen > API:

  1. Klicken Sie auf die Schaltfläche „Hinzufügen“, um eine neue Client-Anwendung zu erstellen.
  2. Geben Sie die Client-ID an (DN für den Zugriff auf den Routenpunkt, der auch für die Autorisierung benötigt wird).
  3. Wenn Sie den Konfigurationsbereich verwenden, aktivieren Sie das Kontrollkästchen 3CX Configuration API-Zugriff für diese Anwendung.
  4. Geben Sie Abteilung und Rolle für den Dienstprinzipal an, um die entsprechende API-Zugriffsebene zu erhalten.
  5. Nachdem Sie erfolgreich eine neue API-Instanz erstellt haben, erhalten Sie einen API-Schlüssel für Ihre Drittanbieteranwendungen. Dieser Schlüssel wird nur einmal angezeigt. Speichern Sie ihn daher unbedingt für die zukünftige Verwendung.

Das war’s! Sie haben die PBX-Konfiguration erfolgreich abgeschlossen.

Bitte beachten: Sie benötigen eine 8SC- oder höhere ENT/AI- bzw. ENT+-Lizenz, um die 3CX Configuration API nutzen zu können.

Wie es funktioniert

RESTful API

Die 3CX Configuration API ist eine RESTful Web API, die auf dem OData-Protokoll basiert und sichere und vielseitige Endpunkte zur Verwaltung und Konfiguration nahezu aller Aspekte des 3CX-Systems bietet. Diese API spiegelt die in der 3CX-Administratorkonsole verfügbare Funktionalität wider und ermöglicht eine programmgesteuerte Kontrolle über Nutzerverwaltung, Abteilungseinrichtung, Anrufweiterleitung, Systemnebenstellen und mehr. Alle Endpunkte sind auf Sicherheit und Zuverlässigkeit ausgelegt und stellen sicher, dass sie weder die Kernfunktionen der PBX noch die Systemstabilität beeinträchtigen.

Weitere Einzelheiten finden Sie in der 3CX Configuration API Endpoint Specification.

Authentifizierungstoken

Die Konfigurations-API unterstützt zwei Arten von Token für den sicheren Zugriff:

  • Multi-Company Admin Tokens: Aktivieren Sie den vollständigen Zugriff zur Verwaltung aller Abteilungen und Einheiten im gesamten 3CX-System. Geeignet für Administratoren in Umgebungen mit mehreren Unternehmen.
  • User Tokens: Gewähren Sie Zugriff, der auf die dem Nutzer zugewiesenen Rollen und Abteilungsberechtigungen beschränkt ist, und ermöglichen Sie so kontrollierten Zugriff auf bestimmte Konfigurationsaufgaben.

JSON und OpenAPI

Dank der OpenAPI-Spezifikation ist die 3CX Configuration API mit verschiedenen Entwicklungstools kompatibel, darunter Postman, und ermöglicht so eine unkomplizierte Integration. Die API akzeptiert Anfragen und Antworten im JSON-Format, sodass Entwickler problemlos mit Konfigurationsaufgaben arbeiten und diese automatisieren können.

Authentifizierungsprozess

Die 3CX Configuration API unterstützt sicheren Zugriff durch zwei Arten von Authentifizierungstoken: Multi-Company-Admin-Token und User Token. Jeder Tokentyp bietet unterschiedliche Zugriffsebenen und ermöglicht so eine flexible Verwaltung von Berechtigungen für verschiedene Rollen und Abteilungen innerhalb der 3CX-Umgebung.

Token

  • Bitte geben Sie die Abteilung und Rolle in Ihren Dienstprinzipaleinstellungen an. Wenn Sie eine Rolle als „Systemeigentümer“ oder „Systemadministrator“ festlegen, werden systemweite Rechte gewährt. Andere Rollen verfügen über entsprechende Rechte.
  • So rufen Sie ihn auf:
  • Rufen Sie den /connect/token Endpunkt mit einer POST-Anweisung mit MIME Typ application/x-www-form-urlencoded.

Der Anforderungstext sollte Folgendes enthalten:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Bei erfolgreicher Authentifizierung wird in der Antwort ein Zugriffstoken zurückgegeben, der dann für nachfolgende API-Anfragen verwendet werden kann.

  • Token Validity: Der Token ist 60 Minuten lang gültig. Danach muss er aktualisiert oder erneut abgerufen werden.

Verwenden von Zugriffstoken

Sobald Sie ein Zugriffstoken erhalten haben, fügen Sie es als Bearer-Token in den Autorisierungsheader Ihrer API-Anfragen ein:

Authorization: Bearer ACCESS_TOKEN

Schnelltest: Überprüfen der Token-Authentifizierung

Um schnell zu überprüfen, ob Ihr Token gültig ist und die API-Verbindung ordnungsgemäß hergestellt wurde, verwenden Sie den Endpunkt „Quick Test“:

  • Endpunkt: GET /xapi/v1/Defs?$select=Id
  • Response: Eine 200 OK-Antwort bestätigt eine gültige Authentifizierung und die Header enthalten die 3CX-Systemversion.

Wichtige Hinweise

  • Ablauf des Tokens: Alle Zugriffstoken laufen nach einer Stunde ab. Anwendungen müssen den Ablauf des Tokens bewältigen, indem sie den Token entweder erneut authentifizieren oder aktualisieren, um eine kontinuierliche Verbindung aufrechtzuerhalten.
  • Sicherheit: Gehen Sie immer sicher mit Tokens um und vermeiden Sie, sie in clientseitigem Code oder ungesicherten Speicherorten verfügbar zu machen.

XAPI-Anwendungsbeispiel

Detaillierte Schritte zum Einrichten einer XAPI-Anwendung mit der PBX-Konfigurations-API finden Sie im XAPI Tutorial Github-Repository. Das Beispiel behandelt die grundlegenden Funktionen und demonstriert API-Aufrufe.

Weiterführende Informationen

Letztes Update

Dieses Dokument wurde zuletzt am 17.Februar 2026 aktualisiert.

https://www.3cx.de/docs/konfiguration-rest-api/