3CX Yapılandırma API'si

Yapılandırma API'si nedir?

3CX V20’de tanıtılan 3CX Yapılandırma API'si (XAPI), 3CX telefon sistemindeki neredeyse her yapılandırma üzerinde programatik kontrol sağlayan ve genellikle yönetici konsolu üzerinden erişilen yetenekleri çoğaltan REST tabanlı bir arayüz sunar. OData standartları ve OpenAPI spesifikasyonları üzerine inşa edilen bu API, geliştiricilerin 3CX ortamını verimli bir şekilde entegre etmelerine, otomatikleştirmelerine ve özelleştirmelerine olanak tanır.

Yapılandırma API'sinin Temel Özellikleri

  • Kapsamlı Yönetim: Departmanları, kullanıcıları, çağrı yönlendirmeyi, sistem abonelerini ve diğer yapılandırmaları yönetmek için uç noktalarla API, kullanıcıların neredeyse tüm idari eylemleri programlı olarak gerçekleştirmesini sağlar. Bir departmanın var olup olmadığını kontrol etmekten paylaşımlı park alanlarını yapılandırmaya kadar 3CX’in hemen hemen her unsuru kod aracılığıyla yönetilebilir.
  • Otomasyon: API, departmanlar oluşturma, kullanıcı rolleri atama ve aboneleri yönetme gibi yaygın yönetim görevlerinin otomasyonuna olanak tanır. Bu, yönetici konsoluna manuel müdahale ihtiyacını azaltır, zamandan tasarruf sağlar ve hata olasılığını en aza indirir.
  • Entegrasyon: API, 3CX telefon sisteminin diğer iş uygulamalarıyla sorunsuz entegrasyonunu kolaylaştırır. Kullanıcı verilerini senkronize etmek, departmanları yönetmek ve 3CX ile harici hizmetler arasında sorunsuz birlikte çalışabilirliği sağlamak için çağrı yönlendirmeyi yapılandırmak için kullanabilirsiniz. 3CX'i daha geniş iş akışlarına entegre etmek, manuel senkronizasyon gerektirmeden iletişimi ve üretkenliği artırır.
  • Ölçeklenebilirlik: Ölçeklenebilirlik düşünülerek tasarlanan API, kuruluşlar büyüdükçe yapılandırmaların etkin bir şekilde yönetilmesini sağlayarak, kullanıcıların, departmanların ve diğer kuruluşların bunaltıcı bir idari yük olmadan kolayca genişletilmesine olanak tanır.

API Entegrasyonunu Yapılandırma

3CX Web İstemcisindeki Yönetici Konsolundan şuraya gidin: Integrations > API:

  1. Yeni bir istemci uygulaması oluşturmak için Add düğmesine basın.
  2. Client ID (Yetkilendirme için de gerekli olan rota noktasına erişim için DN) belirtin.
  3. Yapılandırma kapsamını kullanıyorsanız, bu uygulama için 3CX Configuration API Accss for this application onay kutusunu işaretleyin.
  4. Uygun API erişim düzeyi Servis Sorumlusu için Departmanı ve Rolü belirtin.
  5. Yeni bir API örneği oluşturduktan sonra, üçüncü taraf uygulamalarınız için bir API anahtarı alacaksınız. Bu anahtar yalnızca bir kez gösterilecektir, bu nedenle ileride kullanmak üzere kaydettiğinizden emin olun.

İşte bu kadar! PBX yapılandırmasını başarıyla tamamladınız.

Lütfen dikkat: 3CX Yapılandırma API'sini kullanmak için 8SC+ AI lisansına sahip olmanız gerekir.

Nasıl Çalışır?

RESTful API

3CX Yapılandırma API'si, 3CX sisteminin neredeyse her yönünü yönetmek ve yapılandırmak için güvenli ve çok yönlü uç noktalar sunan OData protokolü üzerine inşa edilmiş bir RESTful Web API’sidir. Bu API, 3CX yönetici konsolunda bulunan işlevselliği yansıtır ve kullanıcı yönetimi, departman kurulumu, çağrı yönlendirme, sistem aboneleri ve daha fazlası üzerinde programatik kontrol sağlar. Tüm uç noktalar, güvenli ve güvenilir olacak şekilde tasarlanmıştır ve çekirdek PBX işlevlerine müdahale etmemelerini veya sistem kararlılığını tehlikeye atmamalarını sağlar.

Daha fazla ayrıntı için 3CX Yapılandırma API Uç Nokta Spesifikasyonuna bakın.

Kimlik Doğrulama Belirteçleri

Yapılandırma API'si, güvenli erişim için iki tür belirteci destekler:

  • Çok Şirketli Yönetici Belirteçleri: 3CX sistemindeki tüm departmanları ve varlıkları yönetmek için tam erişim sağlar, çoklu şirket ortamındaki yöneticiler için uygundur.
  • Kullanıcı Belirteçleri: Kullanıcının atanan rolleri ve departman izinleriyle sınırlı erişim izni verin, belirli yapılandırma görevlerine kontrollü erişim sağlayın.

JSON ve OpenAPI

OpenAPI spesifikasyonu ile 3CX Yapılandırma API'si, Postman dahil olmak üzere çeşitli geliştirme araçlarıyla uyumludur ve böylece basit entegrasyon sağlar. API, JSON biçimli istekleri ve yanıtları kabul eder ve geliştiricilerin yapılandırma görevleriyle çalışmasını ve bunları otomatikleştirmesini kolaylaştırır.

Kimlik Doğrulama Süreci

 3CX Yapılandırma API'si iki tür kimlik doğrulama belirteci aracılığıyla güvenli erişimi destekler: Çok Şirketli Yönetici Belirteçleri ve Kullanıcı Belirteçleri. Her belirteç türü farklı erişim seviyeleri ssğlayarak 3CX ortamındaki çeşitli roller ve departmanlar arasında izinleri yönetmekte esneklik sağlar.

Belirteçler

  • Lütfen Servis Sorumlusu Ayarlarında Departman ve Rol belirtin. Bir rolü "System Owner" veya "System Administrator" olarak ayarlamak sistem genelinde haklar verecektir. Diğer rollerin karşılık karşılık gelen hakları olacaktır.
  • Nasıl Elde Edilir:
  • /connect/token uç noktasını application/x-www-form-urlencoded MIME türüyle bir POST isteğiyle çağırın.

İtek gövdesi şunları içermelidir:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Başarılı kimlik doğrulaması sonrasında, yanıtta bir erişim belirteci döndürülür ve bu belirteç daha sonraki API isteklerinde kullanılabilir.

  • Belirteç Geçerliliği: Belirteç 60 dakika boyunca geçerlidir, bu sürenin sonunda yenilenmesi veya yeniden alınması gerekir.

Erişim Belirteçlerini Kullanma

Bir erişim belirteci elde edildikten sonra, bunu API isteklerinizin Authorization başlığına Bearer Token olarak ekleyin:

Authorization: Bearer ACCESS_TOKEN

Hızlı Test - Belirteç Kimlik Doğrulamasını Doğrulama

Belirtecinizin geçerli olduğunu ve API bağlantısının düzgün şekilde kurulduğunu hızlı bir şekilde doğrulamak için "Quick Test" uç noktasını kullanın:

  • Uç nokta: GET /xapi/v1/Defs?$select=Id
  • Cevap: 200 OK yanıtı geçerli kimlik doğrulamasını onaylar ve başlıklar 3CX sistem sürümünü içerir.

Önemli Notlar

  • Belirteç Son Kullanma Tarihi: Tüm erişim belirteçlerinin süresi bir saat sonra dolar. Uygulamalar, sürekli bir bağlantıyı sürdürmek için belirteci yeniden doğrulayarak veya belirteci yenileyerek belirteç son kullanma tarihini işlemelidir.
  • Güvenlik: Belirteçleri her zaman güvenli bir şekilde işleyin ve bunları istemci tarafı kodunda veya güvenli olmayan depolama konumlarında ifşa etmekten kaçının.

XAPI Uygulama Örneği

PBX Yapılandırma API’si ile bir XAPI uygulama kurulumuna ilişkin ayrıntılı adımlar için lütfen XAPI Eğitimi Github deposuna bakın; örnek, temel işlevleri ve API çağrılarını kapsamaktadır.

Ayrıca bakınız

Son güncelleme

Bu belge en son 13 Mayıs 2025'te güncellendi

https://www.3cx.com.tr/docs/3cx-api-yapilandirma/