API Konfiguracji 3CX

Czym jest API Konfiguracji?

API Konfiguracji 3CX (XAPI), wprowadzone w wersji 20 systemu 3CX, oferuje interfejs oparty na REST, który umożliwia programową kontrolę nad niemal każdym aspektem konfiguracji w systemie telefonicznym 3CX, odwzorowując możliwości dostępne zwykle z poziomu konsoli administratora. Zbudowane w oparciu o standardy OData i specyfikacje OpenAPI, to API pozwala programistom na wydajną integrację, automatyzację i dostosowywanie środowiska 3CX.

Kluczowe cechy API Konfiguracji

  • Kompleksowe zarządzanie: Dzięki punktom końcowym do zarządzania działami, użytkownikami, routingiem połączeń, systemowymi numerami wewnętrznymi i innymi konfiguracjami, API pozwala użytkownikom na programowe wykonywanie niemal wszystkich działań administracyjnych. Od sprawdzania, czy dział istnieje, po konfigurowanie współdzielonych miejsc parkingowych, niemal każdym elementem 3CX można zarządzać za pomocą kodu.
  • Automatyzacja: API pozwala na automatyzację typowych zadań administracyjnych, takich jak tworzenie działów, przypisywanie ról użytkownikom czy zarządzanie numerami wewnętrznymi. Zmniejsza to potrzebę ręcznej interwencji w konsoli administratora, oszczędzając czas i minimalizując ryzyko błędów.
  • Integracja: API ułatwia płynną integrację systemu telefonicznego 3CX z innymi aplikacjami biznesowymi. Można go używać do synchronizacji danych użytkowników, zarządzania działami i konfigurowania routingu połączeń, aby zapewnić płynną interoperacyjność między 3CX a usługami zewnętrznymi. Integracja 3CX z szerszymi przepływami pracy poprawia komunikację i produktywność bez konieczności ręcznej synchronizacji.
  • Skalowalność: Zaprojektowane z myślą o skalowalności, API umożliwia efektywne zarządzanie konfiguracjami w miarę rozwoju organizacji, pozwalając na łatwe dodawanie nowych użytkowników, działów i innych jednostek bez generowania nadmiernego obciążenia administracyjnego.

Konfiguracja integracji API

Z Konsoli Administratora w Kliencie Webowym 3CX przejdź do „Integrations” (Integracje) > „API”:

  1. Naciśnij przycisk „Add” (Dodaj), aby utworzyć nową aplikację kliencką.
  2. Określ „Client ID” (Identyfikator klienta) (numer DN do uzyskiwania dostępu do punktu routingu, który jest również potrzebny do autoryzacji).
  3. Jeśli używasz zakresu „Configuration”, zaznacz pole wyboru „3CX Configuration API Access” (Dostęp do API Konfiguracji 3CX) dla tej aplikacji.
  4. Określ „Department” (Dział) i „Role” (Rola) dla „Service Principal”, aby nadać odpowiedni poziom dostępu do API.
  5. Po pomyślnym utworzeniu nowej instancji API otrzymasz klucz API dla swoich aplikacji firm trzecich. Klucz ten zostanie wyświetlony tylko raz, więc należy go zapisać do przyszłego użytku.

To wszystko! Konfiguracja centrali PBX została pomyślnie zakończona.

Uwaga: Aby korzystać z API Konfiguracji 3CX, należy posiadać licencję 8SC+ AI.

Jak to działa

RESTful API

API Konfiguracji 3CX to REST-owy interfejs Web API zbudowany w oparciu o protokół OData, oferujący bezpieczne i wszechstronne punkty końcowe do zarządzania i konfigurowania niemal każdego aspektu systemu 3CX. To API odzwierciedla funkcjonalność dostępną w konsoli administratora 3CX, umożliwiając programową kontrolę nad zarządzaniem użytkownikami, konfiguracją działów, routingiem połączeń, systemowymi numerami wewnętrznymi i wieloma innymi. Wszystkie punkty końcowe zostały zaprojektowane tak, aby były bezpieczne i niezawodne, zapewniając, że nie zakłócają podstawowych funkcji centrali PBX ani nie zagrażają stabilności systemu.

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

Tokeny uwierzytelniające

API Konfiguracji obsługuje dwa rodzaje tokenów w celu zapewnienia bezpiecznego dostępu:

  • Tokeny administratora Multi-Company: Umożliwiają pełny dostęp do zarządzania wszystkimi działami i jednostkami w całym systemie 3CX, co jest odpowiednie dla administratorów w środowiskach wielofirmowych.
  • Tokeny użytkownika: Zapewniają dostęp ograniczony do ról i uprawnień przypisanych użytkownikowi w ramach jego działu, co pozwala na kontrolowany dostęp do określonych zadań konfiguracyjnych.

JSON i OpenAPI

Dzięki specyfikacji OpenAPI, API Konfiguracji 3CX jest kompatybilne z różnymi narzędziami deweloperskimi, w tym z Postmanem, co umożliwia prostą integrację. API akceptuje żądania i odpowiedzi w formacie JSON, co ułatwia programistom pracę i automatyzację zadań konfiguracyjnych.

Proces uwierzytelniania

API Konfiguracji 3CX zapewnia bezpieczny dostęp poprzez dwa typy tokenów uwierzytelniających: tokeny administratora Multi-Company oraz tokeny użytkownika. Każdy typ tokenu zapewnia inne poziomy dostępu, co pozwala na elastyczne zarządzanie uprawnieniami w ramach różnych ról i działów w środowisku 3CX.

Tokeny

  • Należy określić Dział (Department) i Rolę (Role) w ustawieniach jednostki usługi (Service Principal). Ustawienie roli na „System Owner” (Właściciel systemu) lub „System Admin” (Administrator systemu) nada uprawnienia obejmujące cały system. Pozostałe role będą miały odpowiednie, przypisane im uprawnienia.
  • Jak uzyskać:
  • Wywołaj punkt końcowy /connect/token za pomocą żądania POST z typem MIME application/x-www-form-urlencoded.

Treść żądania 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ępu, który można następnie wykorzystać w kolejnych żądaniach do API.

  • Ważność tokenu: Token jest ważny przez 60 minut, po tym czasie należy go odświeżyć lub uzyskać ponownie.

Używanie tokenów dostępu

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

Authorization: Bearer ACCESS_TOKEN

Szybki test - weryfikacja uwierzytelnienia tokenu

Aby szybko sprawdzić, czy token jest ważny, a połączenie z API zostało poprawnie nawiązane, 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ć wersję systemu 3CX.

Ważne uwagi

  • Wygasanie tokenu: Wszystkie tokeny dostępu wygasają po godzinie. Aplikacje muszą obsługiwać wygasanie tokenów poprzez ponowne uwierzytelnienie lub odświeżenie tokenu w celu utrzymania ciągłości połączenia.
  • Bezpieczeństwo: Zawsze należy postępować z tokenami w sposób bezpieczny i unikać ich eksponowania w kodzie po stronie klienta lub w niezabezpieczonych miejscach przechowywania.

Przykład aplikacji XAPI

Szczegółowe kroki dotyczące konfiguracji aplikacji XAPI z API Konfiguracji PBX można znaleźć w repozytorium na GitHubie z tutorialem XAPI. Przykład obejmuje podstawowe funkcjonalności i demonstracyjne wywołania API.

Zobacz również


Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 17 luty 2026 r.
https://www.3cx.pl/docs/konfiguracja-rest-api/