Kendi santralinizin API ve MCP bağlantıları

Cenaly santralinizi kendi yazılımlarınıza ve yapay zekâ asistanlarınıza bağlayabilirsiniz:

CRM, muhasebe sistemi, kendi siteniz — REST API: arama günlüğü, kayıtlar ve deşifreler, tek tıkla arama, dahililer, yönlendirme, metrikler, arama kuralları, ayarları dışa ve içe aktarma;
Claude, ChatGPT, Cursor, VS Code, Perplexity — MCP sunucusu: anahtarla veya anahtarsız; hesabınıza giriş yapıp erişime izin verirsiniz (OAuth);
Gerçek zamanlı arama olayları — adresinize imzalı webhook'lar veya düzenli sorgulamayla alınan olay akışı.

Tüm işlemler hesap sahibi adına ve yalnızca onun verdiği yetkilerle yürütülür. Her değişiklik, santralin işlem günlüğünde anahtarın veya uygulamanın adıyla görünür.

Üç konu#

Makale	İçeriği
Santralinizin REST API'si	Yetkiler, parametreler ve yanıtlarla tüm yöntemler; hatalar, curl örnekleri ve hazır senaryolar: arama günlüğünü CSV'ye aktarma, CRM'den tek tıkla arama, zamanlanmış gece modu
Santralinizin MCP sunucusu	Claude Code, Cursor, VS Code ve Claude Desktop'a anahtarla; bulut asistanlarına OAuth ile bağlanma, 33 araçlık katalog, örnek diyaloglar, elle JSON-RPC kullanımı
Arama olayı webhook'ları	Webhook oluşturma, tüm olayların gövdeleri, Node.js/Python/PHP/Go ile imza doğrulama, tekrarlar ve mükerrer olaylar, kendi sunucunuz olmadan olay akışı, hata ayıklama

Adresler#

Ne	Adres
REST API	`https://api.cenaly.ge/pbx-api/v1`
MCP sunucusu (streamable HTTP)	`https://api.cenaly.ge/pbx-api/mcp`
Yöntem belgeleri	api.cenaly.ge/pbx-api/v1/docs
OpenAPI 3.1 tanımı	api.cenaly.ge/pbx-api/v1/openapi.json
OAuth meta verileri	`https://api.cenaly.ge/.well-known/oauth-authorization-server/pbx-api`

Hazır adresler ve bağlantı kodları Telefon → API ve MCP → Nasıl bağlanır penceresindedir.

Kendi santrali olan şubede aynı API ve MCP'yi santral sunucusunun kendisi de sunar — buluta uğramayan doğrudan adres: https://sip-<şube kimliği>.cenaly.ge/pbx-api/v1 ve …/pbx-api/mcp. Günlük, kayıtlar, olaylar, durum bilgisi, dahili hatlar, tıkla-ara ve açık/kapalı oradan yanıt verir; kurallar, yapılandırma, webhook'lar, metrikler ve dökümler bulutta kalır (santral cloudUrl ile 501 served_by_cloud döndürür). Doğrudan adres yalnızca anahtarları kabul eder (OAuth — yalnızca bulut adresi). Adresin hazır olup olmadığı «Nasıl bağlanır» penceresinde ve /v1/me ile /v1/locations yanıtlarındaki direct alanında görünür. Tablodaki adresler her zaman çalışır — aynı anahtarla yedek yol.

Anahtar ve yetkiler#

Anahtarı yalnızca hesap sahibi oluşturur: Telefon → API ve MCP → Anahtarlar → Anahtar oluştur. «Santral yöneticisi» rolündeki çalışan anahtarları görmez — anahtar hesap sahibi adına geçerlidir.

cpx_… biçimindeki anahtar yalnızca bir kez gösterilir — oluşturulduktan hemen sonra, bağlantı için hazır bağlantı kodlarıyla birlikte. Bizde yalnızca parmak izi (SHA-256) saklanır, anahtar geri getirilemez — yalnızca yenisi oluşturulabilir.
Anahtar şubelerle (aksi halde gelecektekiler dahil tüm şubeler) ve süreyle (30, 90, 365 gün veya süresiz) sınırlandırılabilir.
«Yetkiler» anahtarın yetkilerini ve şubelerini anında değiştirir: entegrasyon çalışmaya devam eder, yeni yetkiler bir sonraki istekten itibaren geçerli olur.
«İptal et» — hemen ve kalıcı olarak: bu anahtarla yapılan bir sonraki istek 401 alır.
Hesap başına etkin anahtar ve bağlantı sayısı 20'ye kadardır.

Anahtar Authorization: Bearer cpx_… veya X-Api-Key: cpx_… başlığında gönderilir; asla istek URL’sine eklenmez.

Yetkiler hazır bir setle veya onay kutularıyla seçilir:

Yetki	Ne sağlar	Setler
`calls:read`	arama günlüğü, rotasıyla birlikte arama kartı ve olay akışı	CRM, yapay zekâ asistanı, Salt okunur, tümü
`recordings:read`	görüşme kaydı bağlantısı (10 dakika) ve deşifre	CRM, yapay zekâ asistanı, Salt okunur, tümü
`calls:dial`	tek tıkla arama: önce çalışanın telefonu çalar, yanıtlandıktan sonra santral numarayı çevirir	CRM, yapay zekâ asistanı, tümü
`extensions:read`	dahili numaralar, gruplar, yönlendirme, «rahatsız etmeyin»	CRM, yapay zekâ asistanı, Salt okunur, tümü
`extensions:write`	kişisel yönlendirmeyi ve «rahatsız etmeyin» durumunu değiştirme	yapay zekâ asistanı, tümü
`presence:read`	kim müsait, kimin telefonu çalıyor, kim görüşüyor	yapay zekâ asistanı, Salt okunur, tümü
`reports:read`	dönem için çağrı merkezi metrikleri: hizmet düzeyi, bekleme, terk edilen aramalar, AHT, FCR, CSAT, çağrıları nerede kaybediyoruz, kuyruk, hat ve çalışan bazında kırılımlar	Salt okunur, tümü
`routes:read`	numaralar, gelen ve giden kuralları, kural geçmişi ve şubenin açık olup olmadığı	Salt okunur, tümü
`routes:write`	arama kuralları oluşturma, değiştirme, silme ve yeniden sıralama, geçmişten geri alma	yalnızca ayrı onay kutusuyla
`config:export`	santral ayarlarını dosya biçiminde dışa aktarma	yalnızca ayrı onay kutusuyla
`config:import`	ayarları tablolardan içe aktarma: önizleme, ardından uygulama	yalnızca ayrı onay kutusuyla
`webhooks:write`	çağrı olayı webhook'ları oluşturma, değiştirme, test etme ve silme	yalnızca ayrı onay kutusuyla
`daynight:write`	şubeyi gün sonuna veya belirli bir tarihe kadar kapatma, açma — telefondan `*28` ile aynı	yalnızca ayrı onay kutusuyla

Bir şeyi değiştiren veya dakika harcayan yetkiler pencerede sarı renkle işaretlenir. Son beş yetki hiçbir sete, «Tümü» dahil, girmez — bunlar yalnızca bilinçli olarak, ayrı onay kutusuyla verilebilir.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: anahtarsız bağlantı#

Bulut asistanları https://api.cenaly.ge/pbx-api/mcp adresindeki MCP sunucusuna OAuth ile bağlanır; anahtar oluşturmanız gerekmez. Sunucunun her istemciye nereden eklendiği Santralinizin MCP sunucusu makalesinde açıklanır.

Ardından asistan Cenaly giriş penceresini açar. Girişten sonra şunları görürsünüz:

erişimi kim istiyor — uygulama, yanıtın döneceği adresle adlandırılır: «Doğrulanmış bağlayıcı · chatgpt.com» (aynı şekilde — claude.ai, perplexity.ai, vscode.dev, Cursor), «Bu bilgisayardaki program» veya «Bilinmeyen adres» uyarısı. Uygulamanın gönderdiği ad küçük yazıyla gösterilir — onu herkes yazabilir;
yetkiler — uygulamanın istedikleri işaretlenir (eğer «her şeyi» istiyorsa, «Yapay zekâ asistanı» seti işaretlenir); «yalnızca ayrı onay kutusuyla» verilen yetkiler hiçbir zaman önceden işaretlenmez;
şubeler — tümü veya seçilenler.

«İzin ver» sizi asistana geri döndürür ve asistan santralin araçlarını hemen görür. Bağlantı Telefon → API ve MCP → Anahtarlar bölümünde OAuth etiketi ve uygulama adresiyle bir satır olarak görünür — yetkiler de orada değiştirilir ve erişim orada iptal edilir. Aynı uygulamanın yeniden bağlanması, ikinci bir bağlantı oluşturmak yerine yetkilerini günceller.

Bağlantılara yalnızca hesap sahibi izin verebilir.

Kendi bağlayıcılarınız için OAuth#

Yetkilendirme sunucusu MCP yetkilendirme spesifikasyonuna uyar — bunu destekleyen her istemci uygundur:

Tokensiz bir MCP isteği, WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.ge/.well-known/oauth-protected-resource/pbx-api/mcp" başlığıyla 401 alır.
Kaynak meta verileri (RFC 9728) yetkilendirme sunucusunu belirtir — https://api.cenaly.ge/pbx-api; bunun meta verileri (RFC 8414) ise https://api.cenaly.ge/.well-known/oauth-authorization-server/pbx-api adresindedir (ve …/pbx-api/.well-known/openid-configuration).
İstemcinin dinamik kaydı (RFC 7591): POST /pbx-api/oauth/register. Dönüş adresi yalnızca localhost / 127.0.0.1 (herhangi bir port) veya bilinen bir bağlayıcının adresi olabilir (claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, www.perplexity.ai, enterprise.perplexity.ai; Cursor için ayrıca tam olarak cursor://anysphere.cursor-mcp/oauth/callback). İstemcinin giriş yöntemi — none (public istemci), client_secret_post veya client_secret_basic.
PKCE ile yetkilendirme kodu (yalnızca S256): GET /pbx-api/oauth/authorize → sahibinin giriş ve onay penceresi → adresinize code, state ve iss ile dönüş. resource parametresi — MCP sunucusunun adresidir.
Tokenlar: POST /pbx-api/oauth/token. Kod tek kullanımlıktır ve 2 dakika geçerlidir (hatalı code_verifier kodu geçersiz kılar); erişim tokenı — 1 saat; yenileme tokenı — 90 gün, her yenilemede yeni bir tane verilir, önceki çalışmayı durdurur.
İptal: POST /pbx-api/oauth/revoke (RFC 7009) bağlantıyı tümüyle geçersiz kılar — «API ve MCP» penceresindeki «İptal et» gibi.

Erişim tokenı, anahtarın kabul edildiği her yerde kabul edilir: hem MCP'de hem REST'te, sahibin izin verdiği yetkiler ve şubelerle.

Limitler ve hatalar#

Anahtar veya bağlantı başına: dakikada 120 istek ve günde 20 000 (REST ve MCP birlikte).
Tek tıkla arama — ayrıca: dakikada 10 ve günde 300.
Günlük — istek başına 100 aramaya kadar; API, şubenin son 90 gün içindeki en son 400 aramasını görür.
Olay akışı: şube başına son 7 güne ait en fazla 2000 olay, yanıt başına en fazla 500 olay.

Kod	Hata	Ne yapmalı
401	`api_key_missing`, `api_key_invalid`	anahtar yok, iptal edilmiş veya süresi dolmuş; OAuth tokenının süresi dolmuş — yenileyin
403	`scope_required`	anahtarın yetkisi yok — «Yetkiler» bölümüne ekleyin
400	`location_required`	anahtarın birden fazla şubesi var — `location` gönderin
404	`location_not_found`	şube yok veya anahtar başka şubelerle sınırlı
429	`rate_limited`	limit doldu, `Retry-After` saniye sonra tekrar deneyin

Hataların tam listesi: Santralinizin REST API’si.

Güvenlik#

Anahtar bir kez gösterilir ve bizde yalnızca parmak izi olarak saklanır; sızan bir anahtar tek düğmeyle iptal edilir.
OAuth bağlantısına yalnızca sahip izin verir ve erişimin hangi adrese gittiği görülür; izin verilen bağlantı yetkiler ve şubelerle sınırlandırılabilir ve her an iptal edilebilir.
Telefon numaraları müşterilerinizin kişisel verileridir: günlük ve kayıtlar için yetkileri yalnızca gerçekten ihtiyaç duyan entegrasyonlara verin.
Anahtar veya bağlantı üzerinden yapılan tüm değişiklikler, anahtarın veya uygulamanın adıyla santral işlem günlüğünde yer alır.
Webhook’lar gizli anahtarla imzalanır: gönderen adresi yerine her isteğin imzasını doğrulayın. Ayrıntılar: Arama olayı webhook’ları.