Santral API

Base URL: https://api.sanalsantral.com.tr Prefix: /santral

Kimlik Doğrulama

Tüm isteklerde Authorization header’ı ile API anahtarınızı göndermeniz gerekmektedir.

Authorization: Bearer <API_KEY>

API anahtarınızı hesap yöneticinizden temin edebilirsiniz.

Endpointler

1. Agent Login

Bir agenti belirtilen kuyruğa dahil eder.

Özellik	Değer
URL	POST /santral/agentLogin
Auth	Bearer Token

Request Body:

{
"pbxId":1,
"dahiliNo":"1001",
"queue": "100",
"reason":"login"
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
dahiliNo	string	Evet	Dahili numarası
queue	string	Evet	Kuyruk numarası
reason	string	Hayır	Giriş nedeni

Response:

{
  "success": true,
  "message": "Agent login başarılı",
  "data": {},
  "dahiliNo": "1001",
  "queue": "100",
  "reason": "login"
}

2. Agent Logoff

Bir agenti kuyruktan çıkarır.

Özellik	Değer
URL	POST /santral/agentLogoff
Auth	Bearer Token

Request Body:

{
"pbxId": 1,
"dahiliNo": "1001",
"queue": "100",
"reason": "logoff"
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
dahiliNo	string	Evet	Dahili numarası
queue	string	Evet	Kuyruk numarası
reason	string	Hayır	Çıkış nedeni

Response:

{
"success": true,
"message": "Agent logoff başarılı",
"data": {},
"dahiliNo": "1001",
"queue": "100",
"reason": "logoff"
}

3. Simple CDR (Çağrı Detay Kayıtları - Basit)

Basitleştirilmiş çağrı detay kayıtlarını getirir.

Özellik	Değer
URL	POST /santral/simpleCDR veya GET /santral/simpleCDR
Auth	Bearer Token

Request Body / Query Params:

{
"pbxId": 1,
"startDate": "2024-01-01 00:00:00",
"endDate": "2024-01-31 23:59:59",
"callerid": "05551234567",
"dialedNumber": "1001",
"direction": "inbound"
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
startDate	string	Evet	Başlangıç tarihi (YYYY-MM-DD HH:mm:ss)
endDate	string	Evet	Bitiş tarihi (YYYY-MM-DD HH:mm:ss)
callerid	string	Hayır	Arayan numara filtresi
dialedNumber	string	Hayır	Aranan numara filtresi
direction	string	Hayır	Çağrı yönü filtresi (inbound/outbound)

Response:

{
  "success": true,
  "message": "CDR kayıtları başarıyla getirildi",
  "data": [
    {
      "id": 1,
      "tenant": "SANAL",
      "startAt": "2024-01-15 10:30:00",
      "direction": "inbound",
      "callerId": "05551234567",
      "callerName": "John Doe",
      "dialedNumber": "1001",
      "disposition": "ANSWERED",
      "durationSeconds": 120,
      "uniqueId": "1705312200.123",
      "whoAnswered": "1001"
    }
  ]
}

4. CDR (Çağrı Detay Kayıtları - Detaylı)

Detaylı çağrı detay kayıtlarını getirir.

Özellik	Değer
URL	POST /santral/cdr veya GET /santral/cdr
Auth	Bearer Token

Request Body / Query Params:

{
  "pbxId": 1,
  "startDate": "2024-01-01 00:00:00",
  "endDate": "2024-01-31 23:59:59",
  "callerid": "05551234567",
  "direction": "inbound"
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
startDate	string	Evet	Başlangıç tarihi
endDate	string	Evet	Bitiş tarihi
callerid	string	Hayır	Arayan numara filtresi
direction	string	Hayır	Çağrı yönü filtresi

Response:

{
  "success": true,
  "message": "CDR kayıtları başarıyla getirildi",
  "data": [
    {
      "startAt": "2024-01-15 10:30:00",
      "answerAt": "2024-01-15 10:30:05",
      "endAt": "2024-01-15 10:32:05",
      "callerId": "05551234567",
      "dialedNumber": "1001",
      "firstDst": "100",
      "lastDst": "1001",
      "whereLanded": "1001",
      "disposition": "ANSWERED",
      "durationSeconds": 125,
      "billSeconds": 120,
      "uniqueId": "1705312200.123",
      "linkedId": "1705312200.123"
    }
  ]
}

5. Queue Stats (Kuyruk İstatistikleri)

Tüm kuyrukların anlık istatistiklerini getirir.

Özellik	Değer
URL	POST /santral/queueStats veya GET /santral/queueStats
Auth	Bearer Token

Request Body / Query Params:

{
  "pbxId": 1
}

Response:

{
  "success": true,
  "message": "Kuyruk istatistikleri başarıyla getirildi",
  "data": [
    {
      "queueId": "100",
      "queueName": "Destek",
      "agentsAvailable": 5,
      "agentsPaused": 1,
      "agentsFree": 3,
      "agentsOnline": 5,
      "serviceLevel": 80,
      "serviceLevel2": 90,
      "callsInQueue": 2,
      "firstWaiting": 15,
      "secondWaiting": 8,
      "thirdWaiting": 0,
      "callsOnline": 2,
      "talkTime": 3600,
      "holdTime": 120,
      "answeredCalls": 45,
      "callsReceived": 50,
      "abandonedCalls": 3,
      "timedOutCalls": 2,
      "maxHoldTime": 60,
      "averageTalkTime": 80,
      "averageHoldTime": 15
    }
  ]
}

6. Extension Stats (Dahili İstatistikleri)

Tüm dahililerin anlık durumlarını getirir.

Özellik	Değer
URL	POST /santral/extensionStats veya GET /santral/extensionStats
Auth	Bearer Token

Request Body / Query Params:

{
  "pbxId": 1
}

Response:

{
  "success": true,
  "message": "Dahili istatistikleri başarıyla getirildi",
  "data": [
    {
      "extensionNumber": "1001",
      "extensionName": "Ahmet Yılmaz",
      "state": "Idle",
      "uniqueId": "",
      "dndStatus": "off"
    }
  ]
}

7. Extension Status (Dahili Durumu)

Bir dahilinin anlık SIP kayıt durumunu sorgular (kayıt durumu, IP adresi, cihaz bilgisi). Bilgi Asterisk AMI üzerinden gerçek zamanlı alınır.

Özellik	Değer
URL	POST /santral/extensionStatus veya GET /santral/extensionStatus
Auth	Bearer Token

Request Body / Query Params:

{ "pbxId": 1, "extension": "1001" }

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
extension	string	Evet	Sorgulanacak dahili numarası (ör. 1001)

Response (Başarılı):

{
  "success": true,
  "message": "Extension status retrieved",
  "data": {
    "response": "Success",
    "status": "OK (12 ms)",
    "address-ip": "192.168.1.100",
    "sip-useragent": "Yealink SIP-T31P"
  }
}

Response (Hata):

{
  "success": false,
  "message": "Could not retrieve extension status",
  "error": "Timeout"
}

data alanı AMI SIPShowPeer yanıtını içerir; alan adları küçük harfle döner.

8. Extension Queues (Dahilinin Kuyrukları)

Bir dahilinin üye olduğu kuyrukları listeler.

Özellik	Değer
URL	POST /santral/extensionQueues veya GET /santral/extensionQueues
Auth	Bearer Token

Request Body / Query Params:

{
 "pbxId": 1,
 "extensionNumber": "1001"
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
extensionNumber	string	Evet	Dahili numarası

Response:

{
  "success": true,
  "message": "Dahili kuyrukları başarıyla getirildi",
  "data": {
    "extensionNumber": "1001",
    "queues": [
      {
        "queueId": "100",
        "queueName": "Destek"
      },
      {
        "queueId": "200",
        "queueName": "Satış"
      }
    ]
  }
}

9. Get DIDs (DID Numaraları)

PBX’e tanımlı DID (Direct Inward Dialing) numaralarını listeler.

Özellik	Değer
URL	POST /santral/getDIDs veya GET /santral/getDIDs
Auth	Bearer Token

Request Body / Query Params:

{
  "pbxId": 1
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası

Response:

{
  "success": true,
  "message": "DID listesi başarıyla getirildi",
  "data": [
    {
      "id": 1,
      "number": "02121234567"
    },
    {
      "id": 2,
      "number": "08501234567"
    }
  ]
}

10. Get Recording (Ses Kaydı)

Çağrı ses kaydını indirir veya tarayıcıda oynatır. Dosya WAV formatında döner. Tarayıcı üzerinden oynatma için HTTP Range desteği mevcuttur.

Özellik	Değer
URL	GET /santral/getRecording
Auth	Bearer Token

Query Params:

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
id	string	Evet	Kayıt benzersiz kimlik numarası
type	string	Evet	download (indirme) veya play (oynatma)

Headers (Opsiyonel):

Header	Açıklama
Range	bytes=0-1024 şeklinde kısmi içerik isteği (oynatma modu için)

Response (type=download):

• Content-Type: audio/wav

• Content-Disposition: attachment; filename="recording_<id>.wav"

• Dosya doğrudan indirilir.

Response (type=play):

• Content-Type: audio/wav

• Content-Disposition: inline

• Accept-Ranges: bytes

• HTTP 206 Partial Content desteklidir.

Genel Response Yapısı

Tüm endpointler aşağıdaki formatta JSON response döner:

{
  "success": true,
  "message": "İşlem açıklaması",
  "data": {}
}

Alan	Tip	Açıklama
success	boolean	İşlem başarılı ise true, hata durumunda false
message	string	İşlem sonucunu açıklayan mesaj
data	any	İşlem sonucu dönen veri (hata durumunda bulunmayabilir)

Hata Kodları

HTTP Kodu	Açıklama
400	Geçersiz parametre veya eksik zorunlu alan
401	Geçersiz veya eksik API anahtarı
403	Bu kaynağa erişim yetkiniz bulunmamaktadır
404	İstenen kaynak bulunamadı
500	Sunucu hatası