3CX Konfigurations-API

Was ist die Konfigurations-API?

Die 3CX-Konfigurations-API (XAPI), die in 3CX Version 20 eingeführt wurde, bietet eine REST-basierte Schnittstelle, die die programmgesteuerte Steuerung nahezu jedes Konfigurationsaspekts innerhalb des 3CX-Telefonsystems ermöglicht und Funktionen nachbildet, auf die normalerweise über die Verwaltungskonsole zugegriffen wird. Basierend auf OData-Standards und OpenAPI-Spezifikationen ermöglicht diese API Entwicklern die effiziente Integration, Automatisierung und Anpassung der 3CX-Umgebung.

Hauptfunktionen der Konfigurations-API

  • Umfassende Verwaltung: Mit Endpunkten für die Verwaltung von Abteilungen, Nutzern, Anrufweiterleitung, System-Nebenstellen und anderen Konfigurationen ermöglicht die API Nutzern die programmgesteuerte Durchführung nahezu aller virtuellen Verwaltungsaktionen. Vom Überprüfen, ob eine Abteilung existiert, bis hin zum Konfigurieren gemeinsam genutzter Parkplätze kann fast jedes Element von 3CX über Code verwaltet werden.
  • Automatisierung: Die API ermöglicht die Automatisierung allgemeiner Verwaltungsaufgaben wie das Erstellen von Abteilungen, das Zuweisen von Nutzerrollen und das Verwalten von Nebenstellen. Dies reduziert die Notwendigkeit manueller Eingriffe in der Verwaltungskonsole, spart Zeit und minimiert das Fehlerrisiko.
  • Integration: Die API erleichtert die nahtlose Integration des 3CX-Telefonsystems in andere Geschäftsanwendungen. Sie können sie verwenden, um Nutzerdaten zu synchronisieren, Abteilungen zu verwalten und Anrufweiterleitungen zu konfigurieren, um eine reibungslose Interoperabilität zwischen 3CX und externen Diensten zu gewährleisten. Die Integration von 3CX in umfassendere Arbeitsabläufe verbessert die Kommunikation und Produktivität ohne manuelle Synchronisierung.
  • Skalierbarkeit: Die auf Skalierbarkeit ausgelegte API ermöglicht die effiziente Verwaltung von Konfigurationen beim Wachstum von Organisationen und erlaubt die einfache Erweiterung um Nutzer, Abteilungen und andere Entitäten ohne übermäßigen Verwaltungsaufwand.

Konfigurieren der API-Integration

Gehen Sie zu Verwaltungskonsole > Integrationen > API:

  1. Drücken Sie 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 Access für diese Anwendung.
  4. Geben Sie Abteilung und Rolle für den Dienstprinzipal an, um die entsprechende API-Zugriffsebene festzulegen.
  5. Nach der erfolgreichen Erstellung einer neuen API-Instanz erhalten Sie einen API-Schlüssel für Ihre Drittanbieteranwendungen. Dieser Schlüssel wird nur einmal angezeigt. Speichern Sie ihn daher für die zukünftige Verwendung.

Das ist alles! Sie haben die PBX-Konfiguration erfolgreich abgeschlossen.

Bitte beachten Sie: Sie benötigen eine Lizenz mit mindestens 8SC und KI, um die 3CX-Konfigurations-API zu nutzen.

Wie es funktioniert

RESTful API

Die 3CX-Konfigurations-API ist eine auf dem OData-Protokoll basierende RESTful-Web-API, die sichere und vielseitige Endpunkte zur Verwaltung und Konfiguration nahezu jedes Aspekts des 3CX-Systems bietet. Diese API spiegelt die in der 3CX-Verwaltungskonsole verfügbaren Funktionen wider und ermöglicht die programmgesteuerte Steuerung der Nutzerverwaltung, Einrichtung von Abteilungen, Anrufweiterleitung, System-Nebenstellen und mehr. Alle Endpunkte sind so konzipiert, dass sie sicher und zuverlässig sind und die Kernfunktionen der PBX nicht beeinträchtigen oder die Systemstabilität gefährden.

Weitere Details finden Sie in der Spezifikation der Endpunkte der 3CX-Konfigurations-API.

Authentifizierungstoken

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

  • Multi-Mandanten-Admin-Token: Ermöglichen den vollen Zugriff zur Verwaltung aller Abteilungen und Entitäten im gesamten 3CX-System, geeignet für Administratoren in Multi-Mandanten-Umgebungen.
  • Nutzer-Token: Gewähren Zugriff beschränkt auf die zugewiesenen Rollen und Abteilungsberechtigungen des Nutzers und bieten kontrollierten Zugriff auf bestimmte Konfigurationsaufgaben.

JSON and OpenAPI

Mit ihrer OpenAPI-Spezifikation ist die 3CX-Konfigurations-API mit verschiedenen Entwicklungstools, einschließlich Postman, für eine einfache Integration kompatibel. Die API akzeptiert JSON-formatierte Anfragen und Antworten, was Entwicklern das Arbeiten mit Konfigurationsaufgaben und deren Automatisierung erleichtert.

Authentifizierungsprozess

Die 3CX-Konfigurations-API unterstützt den sicheren Zugriff über zwei Arten von Authentifizierungstoken: Multi-Mandanten-Admin-Token und Nutzer-Token. Jede Token-Art bietet unterschiedliche Zugriffsebenen und ermöglicht so eine flexible Verwaltung der Berechtigungen über verschiedene Rollen und Abteilungen innerhalb der 3CX-Umgebung hinweg.

Token

  • Bitte geben Sie die Abteilung und Rolle in Ihren Dienstprinzipal-Einstellungen an. Die Einstellung einer Rolle als "Eigentümer des Systems" oder "Systemadministrator" gewährt systemweite Rechte. Andere Rollen verfügen über entsprechende Rechte.
  • So erhalten Sie Token:
  • Rufen Sie den Endpunkt /connect/token mit einer POST-Anfrage mit dem MIME-Typ application/x-www-form-urlencoded auf.

Der Anfrage-Text sollte Folgendes enthalten:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

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

  • Token-Gültigkeit: Das Token ist 60 Minuten lang gültig. Danach muss es aktualisiert oder erneut angefordert werden.

Verwenden von Zugriffstoken

Sobald Sie ein Zugriffstoken erhalten haben, fügen Sie es als Bearer-Token in den Header Authorization 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 "Schnelltest":

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

Wichtige Hinweise

  • Token-Ablauf: Alle Zugriffstoken laufen nach einer Stunde ab. Anwendungen müssen das Ablaufen von Token behandeln, indem sie sich erneut authentifizieren oder das Token aktualisieren, um eine kontinuierliche Verbindung aufrechtzuerhalten.
  • Sicherheit: Behandeln Sie Token stets sicher und vermeiden Sie es, sie in clientseitigem Code oder an unsicheren Speicherorten offenzulegen.

XAPI-Anwendungsbeispiel

Detaillierte Schritte zum Einrichten einer XAPI-Anwendung mit der PBX-Konfigurations-API finden Sie im XAPI-Tutorial-GitHub-Repository. Das Beispiel deckt grundlegende Funktionen und API-Aufrufe ab.

Seiehe auch

Letztes Update

Dieses Dokument wurde zuletzt am 22.September 2026 aktualisiert.

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