API Konfiguracji 3CX

Czym jest Configuration API?

Interfejs 3CX Configuration API (XAPI), wprowadzony w wersji 3CX Version 20, oferuje interfejs oparty na architekturze REST, który umożliwia programowe zarządzanie niemal każdym elementem konfiguracji centrali telefonicznej 3CX, zapewniając możliwości analogiczne do tych w konsoli administracyjnej. Stworzony w oparciu o standardy OData oraz specyfikację OpenAPI, interfejs API pozwala deweloperom sprawnie integrować, automatyzować i dostosowywać środowisko 3CX.

Kluczowe funkcje Configuration API

  • Kompleksowe zarządzanie: Dzięki punktom końcowym do obsługi działów, użytkowników, kierowania połączeń, numerów wewnętrznych systemu i pozostałych ustawień, interfejs API umożliwia programowe wykonywanie niemal wszystkich czynności administracyjnych. Od weryfikacji istnienia działów po konfigurację współdzielonych miejsc parkowania połączeń – praktycznie każdym elementem 3CX można zarządzać z poziomu kodu.
  • Automatyzacja: Interfejs API pozwala zautomatyzować codzienne zadania administracyjne, takie jak zakładanie działów, przypisywanie ról użytkownikom czy zarządzanie numerami wewnętrznymi. Ogranicza to konieczność ręcznej pracy w konsoli administracyjnej, oszczędza czas i minimalizuje ryzyko pomyłek.
  • Integracja: Interfejs API umożliwia płynną integrację systemu telefonicznego 3CX z innymi aplikacjami biznesowymi. Możesz go używać do synchronizacji danych użytkowników, zarządzania działami oraz konfigurowania kierowania połączeń, aby zapewnić pełną interoperacyjność między systemem 3CX a usługami zewnętrznymi. Włączenie 3CX w szersze procesy biznesowe usprawnia komunikację i podnosi wydajność pracy bez konieczności ręcznego przesyłania danych.
  • Skalowalność: Zaprojektowany z myślą o skalowalności, interfejs API pozwala sprawnie zarządzać konfiguracją w miarę rozwoju organizacji. Umożliwia łatwe dodawanie kolejnych użytkowników, działów i zasobów bez konieczności wykonywania pracochłonnych czynności obsługowych.

Konfiguracja integracji API

Przejdź do Konsoli administracyjnej > „Integrations” (Integracje) > „API”.

  1. Kliknij przycisk „Add” (Dodaj), aby utworzyć nową aplikację kliencką.
  2. Określ identyfikator klienta „Client ID” (DN do uzyskania dostępu do punktu trasy, który jest również potrzebny do autoryzacji).
  3. Jeśli używasz zakresu konfiguracji (Configuration scope), zaznacz pole wyboru „3CX Configuration API Access” (Dostęp do 3CX Configuration API) dla tej aplikacji.
  4. Określ dział („Department”) oraz rolę („Role”) dla konta usługi (Service Principal), aby uzyskać odpowiedni poziom dostępu do API.
  5. Po pomyślnym utworzeniu nowej instancji API otrzymasz klucz API dla swoich aplikacji zewnętrznych. Klucz ten zostanie wyświetlony tylko raz, dlatego pamiętaj, aby zapisać go do użycia w przyszłości.

I to wszystko! Pomyślnie ukończono konfigurację centrali PBX.

Uwaga: Aby korzystać z 3CX Configuration API, musisz posiadać licencję 3CX AI od 8 jednoczesnych połączeń (8SC) wzwyż.

Jak to działa

RESTful API

Interfejs 3CX Configuration API to interfejs RESTful Web API zbudowany na protokole OData, oferujący bezpieczne i wszechstronne punkty końcowe do zarządzania i konfigurowania niemal każdego aspektu systemu 3CX. Ten interfejs API odzwierciedla funkcjonalność dostępną w konsoli administracyjnej 3CX, umożliwiając programowe zarządzanie użytkownikami, konfiguracją działów, kierowaniem połączeń, numerami wewnętrznymi systemu i wieloma innymi elementami. Wszystkie punkty końcowe zostały zaprojektowane tak, aby działały bezpiecznie i niezawodnie, bez zakłócania podstawowych funkcji centrali PBX ani naruszania stabilności systemu.

Więcej szczegółów można znaleźć w specyfikacji punktów końcowych 3CX Configuration API Endpoint Specification.

Tokeny uwierzytelniające

Configuration API obsługuje dwa typy tokenów dla zapewnienia bezpiecznego dostępu:

  • Tokeny administratora wielofirmowego (Multi-Company Admin Tokens): zapewniają pełny dostęp do zarządzania wszystkimi działami i zasobami w całym systemie 3CX; są przeznaczone dla administratorów w środowiskach wielofirmowych.
  • Tokeny użytkownika (User Tokens): przyznają dostęp ograniczony do ról przypisanych użytkownikowi oraz uprawnień w ramach danego działu, pozwalając na wykonywanie określonych zadań konfiguracyjnych.

JSON oraz OpenAPI

Dzięki specyfikacji OpenAPI interfejs 3CX Configuration API jest w pełni kompatybilny z popularnymi narzędziami deweloperskimi (w tym z programem Postman), co bardzo ułatwia proces integracji. Interfejs API przyjmuje żądania i zwraca odpowiedzi w formacie JSON, co ułatwia pracę deweloperom oraz przyspiesza automatyzację zadań.

Proces uwierzytelniania

Interfejs 3CX Configuration API obsługuje bezpieczny dostęp za pośrednictwem dwóch typów tokenów uwierzytelniających: tokenów administratora wielofirmowego oraz tokenów użytkownika. Każdy typ tokena zapewnia inny poziom dostępu, co pozwala elastycznie zarządzać uprawnieniami w ramach różnych ról i działów w środowisku 3CX.

Tokeny

  • Określ dział („Department”) oraz rolę („Role”) w ustawieniach konta usługi (Service Principal). Ustawienie roli jako „System Owner” (Właściciel systemu) lub „System Admin” (Administrator systemu) przyzna uprawnienia dla całego systemu. Inne role będą posiadać odpowiednio mniejsze uprawnienia.
  • Jak uzyskać token:
  • Wywołaj punkt końcowy /connect/token za pomocą żądania POST z typem MIME application/x-www-form-urlencoded.

Treść żądania (body) powinna zawierać:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Po pomyślnym uwierzytelnieniu w odpowiedzi zostanie zwrócony token dostępowy, który należy wykorzystywać w kolejnych zapytaniach do API.

  • Ważność tokena: Token jest ważny przez 60 minut, po czym należy go odświeżyć lub wygenerować ponownie.

Używanie tokenów dostępowych

Po uzyskaniu tokena dostępowego należy dołączyć go do nagłówka Authorization w żądaniach API jako token Bearer:

Authorization: Bearer ACCESS_TOKEN

Szybki test – weryfikacja uwierzytelnienia tokena

Aby szybko sprawdzić, czy token jest prawidłowy, a połączenie z API zostało nawiązane poprawnie, użyj punktu końcowego „Quick Test”:

  • Punkt końcowy: GET /xapi/v1/Defs?$select=Id
  • Odpowiedź: Odpowiedź 200 OK potwierdza prawidłowe uwierzytelnienie, a nagłówki będą zawierać informację o wersji systemu 3CX.

Ważne uwagi

  • Wygaśnięcie tokena: Wszystkie tokeny dostępowe wygasają po jednej godzinie. Aplikacje muszą obsługiwać proces wygasania tokenów poprzez ponowne uwierzytelnienie lub odświeżenie tokena, aby zachować ciągłość połączenia.
  • Bezpieczeństwo: Zawsze przechowuj i obsługuj tokeny w bezpieczny sposób. Unikaj umieszczania ich w kodzie wykonywanym po stronie klienta oraz w niezabezpieczonych miejscach.

Przykład aplikacji XAPI

Szczegółowe kroki dotyczące konfigurowania aplikacji XAPI z wykorzystaniem PBX Configuration API można znaleźć w repozytorium GitHub XAPI Tutorial; przykład prezentuje podstawowe funkcje oraz sposób wykonywania wywołań API.

Zobacz również


Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 10 września 2026 r.
https://www.3cx.pl/docs/konfiguracja-rest-api/