Call API

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

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. Dial First (Çağrı Başlatma)

Yeni bir çağrı başlatır. Sistem önce belirtilen dahiliyi arar, dahili cevapladıktan sonra hedef numarayı çağırır.

Özellik	Değer
URL	POST /call/dialFirst
Auth	Bearer Token

Request Body:

{
  "pbxId": 1,
  "dialNumber": "05551234567",
  "callerId": "02121234567",
  "callerExtension": "1001-TESTPBX",
  "destination": {
    "type": "mobile",
    "target": "05559876543"
  }
}

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
dialNumber	string	Evet	Aranacak numara
callerId	string	Evet	Arayan numara olarak görünecek numara. Müşteriye ait ve aktif bir numara olmalıdır; değilse çağrı 403 ile reddedilir.
callerExtension	string	Evet (mask: Hayır)	Çağrıyı başlatan dahili numarası. mask tipinde zorunlu değildir.
destination	object	Evet	Hedef bilgisi
destination.type	string	Evet	Hedef tipi: mobile, pi, mask
destination.target	string	Evet	Hedef numarası (mask tipinde ikinci cep telefonu)
destination.params	object	Hayır	Pi uygulaması için gönderilecek parametreler.

Response (Başarılı):

{
  "success": true,
  "message": "Çağrı başarıyla başlatıldı",
  "data": {
    "ActionID": "1705312200123"
  }
}

Response (Hata):

{
  "success": false,
  "message": "Çağrı başlatılamadı",
  "error": "Originate failed"
}

Maskeli Çağrı (destination.type: mask):

İki cep telefonunu santral üzerinden birbirine bağlar. Önce dialNumber aranır; cevaplanınca destination.target aranır. İki taraf da arayan numarası olarak callerId'yi (dış hat numaranızı) görür, birbirinin gerçek numarasını görmez.

Request Body:

{
  "pbxId": 1,
  "dialNumber": "05321234567",
  "callerId": "08501234567",
  "destination": {
    "type": "mask",
    "target": "05339876543"
  }
}

Alan	Tip	Zorunlu	Açıklama
dialNumber	string	Evet	İlk aranacak cep telefonu (A)
destination.target	string	Evet	A cevaplayınca aranacak cep telefonu (B); A ile aynı olamaz
callerId	string	Evet	İki tarafa görünecek dış hat numaranız. Müşteriye ait ve aktif olmalıdır.
callerExtension	string	Hayır	Verilirse çağrı bu dahili adına çıkar (yönlendirme profili, çağrı kaydı)
async	boolean	Hayır	true ise hemen döner; aksi halde ilk aramanın sonucu (callResult.dialstatus) beklenir

Cep telefonu numaraları 5321234567, 05321234567, 905321234567 ya da +905321234567 biçiminde gönderilebilir. Sabit hat numaraları kabul edilmez.

Hata Durumları:

HTTP	error	Açıklama
400	INVALID_GSM	dialNumber ya da destination.target geçerli bir cep telefonu değil veya ikisi aynı
400	CALLER_ID_REQUIRED	callerId gönderilmedi
403	CALLER_ID_NOT_OWNED	callerId size ait aktif bir numara değil
503	CALLER_ID_UNVERIFIED	callerId şu anda doğrulanamadı; çağrı başlatılmadı, tekrar deneyin

Örnek Kullanımlar:

Önce dahiliyi arayıp sonra cep telefonuna bağlama isteği: (Örnek santral kodu TESTPBX)

{
    "pbxId": 9091279,
    "dialNumber": "1016",
    "callerId": "902202221100",
    "callerExtension": "1016-TESTPBX",
    "destination": {
        "type": "mobile",
        "target": "05559876543"
    }
}

Önce cep telefonunu sonra dahiliye bağlama isteği: (Örnek santral kodu TESTPBX)

{
    "pbxId": 1,
    "dialNumber": "05559876543",
    "callerId": "02121234567",
    "callerExtension": "1016-TESTPBX",
    "destination": {
      "type": "mobile",
      "target": "1016-TESTPBX"
    }
}

Önce cep telefonunu sonra Pi uygulamasına bağlama isteği: (Örnek santral kodu: TESTPBX)

{
    "pbxId": 1,
    "dialNumber": "05559876543",
    "callerId": "02121234567",
    "callerExtension": "1001-TESTPBX",
    "destination": {
      "type": "pi",
      "target": "26",
      "params": {
        "orderId": "ORD-12345",
        "customerId": "C-789"
      }
    }
}

İki cep telefonunu maskeli olarak birbirine bağlama isteği (iki taraf da 08501234567 numarasını görür):

{
  "pbxId": 1,
  "dialNumber": "05321234567",
  "callerId": "08501234567",
  "destination": {
    "type": "mask",
    "target": "05339876543"
  }
}

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	Eksik veya geçersiz parametre
401	Geçersiz veya eksik API anahtarı
403	Bu kaynağa erişim yetkiniz bulunmamaktadır
404	İstenen kaynak bulunamadı
500	Sunucu hatası