Yapay Zeka Analiz
Bu doküman, müşterilerin kendi sistemlerinden SanalSantral AI platformuna entegre olması için sunulan tüm genel (public) API uç noktalarını açıklar: ses yükleme/transkripsiyon, çağrı kayıtları, ses kayıtları, AI analiz sonuçları, transkriptler ve giden webhook bildirimleri.
- Temel adres:
https://ai.sanalsantral.com.tr - Kimlik doğrulama:
Authorization: Bearer ss_live_... - Format: JSON (yükleme uçları
multipart/form-data)
1. Kimlik Doğrulama
Tüm çağrılar, firmanıza özel üretilen API anahtarını Bearer token olarak Authorization başlığında taşımalıdır:
Authorization: Bearer ss_live_XXXXXXXXXXXXXXXXXXXX
- Anahtar SanalSantral tarafından firmanıza özel verilir. Firma ve santral (PBX)
yetkileri anahtardan çözülür; istekte ayrıca firma kimliği göndermenize gerek yoktur.
- Anahtarınızı gizli tutun; sızması durumunda SanalSantral ile iletişime geçin.
> Geriye dönük (deprecated) yöntem: Yalnızca POST /api/transcribe için,
> Bearer başlığı yerine form alanı olarak company_id + api_key göndermek de
> kabul edilir (bkz. bu dokümanın sonundaki Ek bölümü). Yeni entegrasyonlar
> Bearer yöntemini kullanmalıdır.
Ortak hata gövdesi
Tüm uçlar hata durumunda aynı şekli döner:
{ "success": false, "error": "açıklama", "code": "makine_kodu" }
| HTTP | Anlamı |
|---|---|
| 400 | Eksik/geçersiz parametre |
| 401 | Anahtar eksik veya geçersiz (auth_missing, auth_invalid) |
| 403 | Anahtar geçerli ama bu kayda/PBX'e yetkisiz (no_pbx, forbidden_pbx) |
| 404 | Kayıt bulunamadı |
2. Ses Yükleme ve Transkripsiyon
POST /api/transcribe · Content-Type: multipart/form-data
Bir ses dosyası yükler; kayıt işleme kuyruğuna alınır, metne dönüştürülür ve (ayarlıysa) AI analizi yapılır.
Başlık: Authorization: Bearer ss_live_...
Form alanları:
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| file | File | ✔ | Ses dosyası (.wav, .mp3 …) |
| santral_id | Number | – | Santral (PBX) kimliği |
| kullanici_id | Number | – | Kullanıcı kimliği |
| sure | Number | – | Çağrı süresi (saniye) |
| baslangic_zamani | String | – | Başlangıç zamanı (ISO önerilir) |
| src | String | – | Arayan numara |
| dst | String | – | Aranan numara |
| realsrc | String | – | Gerçek arayan (dahili) |
| userfield | String | – | Serbest alan |
| metadata | String | – | Ek JSON verisi / notlar |
Yanıt 200:
{ "uniqueid": "…", "filepath": "…", "jobId": "…" }
Dönen uniqueid, diğer uçlarda (analiz, transkript, kayıt) o çağrıyı sorgulamak için kullanılır.
Örnek:
curl -X POST https://ai.sanalsantral.com.tr/api/transcribe \
-H "Authorization: Bearer ss_live_..." \
-F "[email protected]" \
-F "santral_id=123" \
-F "src=902121112233" -F "dst=05001112233" \
-F "sure=120" -F "baslangic_zamani=2026-01-05T14:30:00"
3. Çağrı Kayıtları (CDR)
GET /api/external/cdr
Tarih aralığındaki çağrı kayıtlarını döner.
Parametreler (query):
| Param | Zorunlu | Açıklama |
|---|---|---|
| startDate | ✔ | YYYY-MM-DD |
| endDate | ✔ | YYYY-MM-DD |
| pbxId | – | Belirli santral; verilmezse anahtara bağlı tüm santraller |
pbxId verilirse anahtarınıza ait olmalıdır (aksi halde 403).
Yanıt 200:
{
"success": true,
"data": [
{ "callerId": "…", "dialedNumber": "…", "direction": "…",
"durationSeconds": 42, "disposition": "…", "uniqueId": "…",
"startAt": "…", "pbxId": 123 }
],
"pbxIds": [123],
"errors": []
}
Örnek:
curl "https://ai.sanalsantral.com.tr/api/external/cdr?startDate=2026-06-01&endDate=2026-06-30" \
-H "Authorization: Bearer ss_live_..."
4. Ses Kaydı İndirme / Dinleme
GET /api/external/recording
Bir çağrının ses kaydını audio/wav olarak stream eder. Range başlığı desteklenir (kısmi indirme / oynatma).
Parametreler (query):
| Param | Zorunlu | Açıklama |
|---|---|---|
| uniqueid | ✔ | Çağrının benzersiz kimliği |
| pbxId | ✔ | Çağrının santral kimliği (anahtarınıza ait olmalı) |
| download | – | 1 → dosya olarak indir; yoksa satır içi oynatma |
Yanıt: 200/206 + audio/wav gövdesi. Bulunamazsa 404.
Örnek:
curl "https://ai.sanalsantral.com.tr/api/external/recording?uniqueid=abc123&pbxId=123&download=1" \
-H "Authorization: Bearer ss_live_..." -o kayit.wav
5. AI Analiz Sonuçları (list + detay)
GET /api/external/analyze
Sadece okuma. uniqueid verirseniz detay, vermezseniz liste döner.
Parametreler (query):
| Param | Zorunlu | Açıklama |
|---|---|---|
| uniqueid | – | Verilirse o çağrının detay sonucu |
| take | – | Sayfa boyutu (liste; varsayılan 20, maks 100) |
| skip | – | Atlanacak kayıt (liste) |
| srcLike / dstLike / realSrcLike | – | Arayan / aranan / dahili içerir filtresi |
| cagriDateOp + cagriDateValue | – | Tarih filtresi (`lt\ |
Yanıt 200:
{ "success": true, "data": [ /* prompt/skor sonuçları */ ], "totalCount": 1 }
Örnekler:
# detay
curl "https://ai.sanalsantral.com.tr/api/external/analyze?uniqueid=abc123" \
-H "Authorization: Bearer ss_live_..."
# liste
curl "https://ai.sanalsantral.com.tr/api/external/analyze?take=20&skip=0" \
-H "Authorization: Bearer ss_live_..."
6. Transkriptler (list + detay)
GET /api/external/transcripts
Sadece okuma. uniqueid verirseniz detay (transkript metni + konuşma segment'leri), vermezseniz liste döner.
Parametreler (query):
| Param | Zorunlu | Açıklama |
|---|---|---|
| uniqueid | – | Verilirse o çağrının detayı (metin + segment'ler) |
| take | – | Sayfa boyutu (liste; varsayılan 20, maks 100) |
| skip | – | Atlanacak kayıt (liste) |
| srcLike / dstLike / realSrcLike | – | Arayan / aranan / dahili içerir filtresi |
| cagriDateOp + cagriDateValue | – | Tarih filtresi (`lt\ |
Yanıt (detay) 200:
{
"success": true,
"data": {
"uniqueid": "abc123",
"transcript_text": "...",
"src": "...", "dst": "...", "sure": 42,
"segments": [ { "speaker_id": "0", "text": "...", "start": 0.0, "end": 2.1 } ]
}
}
Bulunamazsa 404. segments yoksa null olabilir.
Örnekler:
# liste
curl "https://ai.sanalsantral.com.tr/api/external/transcripts?take=20&skip=0" \
-H "Authorization: Bearer ss_live_..."
# detay
curl "https://ai.sanalsantral.com.tr/api/external/transcripts?uniqueid=abc123" \
-H "Authorization: Bearer ss_live_..."
7. Webhook Bildirimleri (giden)
Panelden (Ayarlar → Bildirimler) bir webhook URL'i tanımlayabilirsiniz. Belirlediğiniz koşul (anahtar kelime eşleşmesi veya tüm çağrılar) oluştuğunda SanalSantral, tanımladığınız URL'e application/json gövdeyle POST gönderir.
Gövde, sizin tanımladığınız şablona göre doldurulur. Kullanılabilir değişkenler:
| Değişken | Açıklama |
|---|---|
| [arayan] | Arayan numara |
| [aranan] | Aranan numara |
| [dahili] | Dahili |
| [cagri_zamani] | Çağrı zamanı (ISO) |
| [sure] | Süre (saniye) |
| [santral_id] | Santral (PBX) kimliği |
| [arama_yonu] | Yön (Gelen / Giden) |
| [uniqueid] | Çağrının benzersiz kimliği |
| [kelime] | Eşleşen anahtar kelime |
| [konusma_icerigi] | Konuşma metni (JSON string) |
| [metadata] | Çağrı meta verisi |
Ek: Eski Doküman — "AI Analiz" (transcribe · legacy)
> Bu bölüm, POST /api/transcribe için eski (deprecated) kimlik doğrulama
> yöntemini (company_id + api_key form alanları) anlatan orijinal dokümandır.
> Mevcut entegrasyonlar çalışmaya devam eder; yeni entegrasyonlar yukarıdaki
> Authorization: Bearer ss_live_... yöntemini kullanmalıdır.
AI Analiz
Bu doküman, harici sistemlerden ses dosyalarının yüklenmesi ve metne dönüştürülmesi (transkripsiyon) işlemi için kullanılan API uç noktasını tarif eder.
1. Genel Bilgiler
Bu servis, multipart/form-data formatında gönderilen ses kayıtlarını ve çağrı detaylarını kabul eder. Yüklenen dosyalar işleme sırasına alınır ve metne dönüştürülür.
- URL:
https://ai.sanalsantral.com.tr/api/transcribe - Method:
POST - Content-Type:
multipart/form-data
2. Kimlik Doğrulama
API kullanımı için size sağlanan company_id ve api_key bilgilerini her istekte göndermeniz gerekmektedir.
3. Parametreler
Aşağıdaki parametreler form-data gövdesi (body) içerisinde gönderilmelidir.
| Parametre | Tip | Zorunluluk | Açıklama |
|---|---|---|---|
| file | File | Zorunlu | Yüklenecek ses dosyası. (Örn: .wav, .mp3) |
| company_id | Number | Zorunlu | Şirket ID'niz. |
| api_key | String | Zorunlu | Size özel tanımlanmış API anahtarı. |
| sure | Number | Zorunlu | Çağrının saniye cinsinden süresi. |
| baslangic_zamani | String | Opsiyonel | Çağrının başlangıç tarihi/zamanı (ISO formatı önerilir). |
| src | String | Opsiyonel | Arayan numara bilgisi. |
| dst | String | Opsiyonel | Aranan numara bilgisi. |
| metadata | String | Opsiyonel | Çağrı ile ilgili ek JSON verisi veya notlar. |
4. Örnek cURL İsteği
Aşağıdaki örnekte audio.wav dosyasının API'ye nasıl gönderileceği gösterilmiştir.
curl --location 'https://ai.sanalsantral.com.tr/api/transcribe' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"/path/to/your/audio.wav"' \
--form 'company_id="12345"' \
--form 'api_key="test_123456789"' \
--form 'src="05551112233"' \
--form 'dst="02123334455"' \
--form 'sure="120"' \
--form 'baslangic_zamani="2026-01-05T14:30:00"'