Çağrı Maskeleme API

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

Çağrı maskeleme, iki tarafın birbirinin gerçek telefon numarasını görmeden konuşmasını sağlar. Taraflar size ait bir dış hat numarası (dial_number) üzerinden birbirine bağlanır. Bu API maskeleme kayıtlarını oluşturur, sorgular ve iptal eder; çağrının bağlanması santral tarafından yapılır.

Hızlı Kullanım: Kayıt Oluşturmadan Maskeli Çağrı

İki cep telefonunu hemen birbirine bağlamak istiyorsanız aşağıdaki kayıt işlemlerini yapmanız gerekmez. Call API içindeki Dial First uç noktasını destination.type: mask ile çağırmanız yeterlidir. Santral önce dialNumber numarasını arar, cevaplanınca destination.target numarasını arar. İki taraf da arayan numarası olarak callerId'yi (dış hat numaranızı) görür, birbirinin gerçek numarasını görmez.

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

Request Body:

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

Alan	Tip	Zorunlu	Açıklama
pbxId	number	Evet	PBX kimlik numarası
dialNumber	string	Evet	İlk aranacak cep telefonu (A)
callerId	string	Evet	İki tarafa görünecek dış hat numaranız. Size ait ve aktif olmalıdır.
destination.type	string	Evet	mask
destination.target	string	Evet	A cevaplayınca aranacak cep telefonu (B)

Opsiyonel alanlar (callerExtension, async) ve hata kodları için Call API dokümanına bakın.

Hangisini kullanmalıyım?

Dial First (mask): İki tarafı şu anda siz bağlarsınız; çağrıyı kendi sisteminizden başlatırsınız. Kayıt oluşturmanız gerekmez.
Maskeleme kayıtları (aşağıdaki uç noktalar): Taraflardan biri daha sonra dış hat numaranızı kendisi aradığında santralin onu kime bağlayacağını belirler (sipariş kodu, GSM eşleşmesi ya da QR).

Maskeleme Tipleri

order (sipariş kodu): Arayan kişi dış hat numaranızı arar ve kodu tuşlar; çağrı gsm numarasına bağlanır. Kodu sistem üretebilir ya da siz gönderebilirsiniz.
match (GSM ↔ GSM eşleşme): gsm ve gsm_b numaralarından hangisi dış hat numaranızı ararsa diğerine bağlanır.
qr (QR / link): Dönen qr_url karşı tarafa iletilir. Karşı taraf linki açar, cep telefonu numarasını girip "Ara"ya basar ve iki taraf da aranır. Linki ilk kullanan kazanır.

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.

Genel Kurallar

/santral/mask uç noktaları yalnızca POST ve JSON gövde kabul eder; pbxId gönderilmesi gerekmez.
Alan adları snake_case yazılır (dial_number, gsm_b, ttl_minutes).
dial_number size ait aktif bir numara olmalıdır; değilse 403 NUMBER_NOT_OWNED döner ve kayıt oluşturulmaz.
Cep telefonu numaraları 5321234567, 05321234567, 905321234567 ya da +905321234567 biçiminde gönderilebilir; boşluk, tire, nokta ve parantez kullanılabilir. Sabit hat ve eksik/fazla haneli numaralar 400 INVALID_GSM ile reddedilir.
Tarihler UTC ve YYYY-MM-DD HH:MM:SS biçimindedir. Numaralar 0XXXXXXXXXX biçiminde döner.
Kayıtlar listelenemez. Her sorgu tek kayıt döner ya da 404 NOT_FOUND verir; yalnızca aktif ve süresi dolmamış kayıtlar bulunur.
Kayıtlar ttl_minutes süresi dolunca kendiliğinden kapanır. İşiniz bitince revoke ile erken kapatabilirsiniz.

Endpointler

1. Kayıt Oluştur

Yeni bir maskeleme kaydı oluşturur.

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

Request Body (order):

{
  "type": "order",
  "dial_number": "08501234567",
  "gsm": "0532 123 45 67",
  "ref": "SIP-1001",
  "code_length": 5,
  "ttl_minutes": 60
}

Alan	Tip	Zorunlu	Açıklama
type	string	Evet	order, match ya da qr
dial_number	string	Evet	Aranacak dış hat numaranız
gsm	string	Evet	Cep telefonu A
gsm_b	string	match için Evet	Cep telefonu B; gsm ile aynı olamaz
code	string	Hayır	Yalnız order: 4-6 haneli kendi kodunuz. Aynı dış hat numarasında aktif bir kodla çakışırsa 409 CONFLICT döner.
code_length	number	Hayır	Yalnız order: code gönderilmezse üretilecek kodun uzunluğu (4-6, varsayılan 4)
ttl_minutes	number	Hayır	Geçerlilik süresi, 1-1440 dakika (varsayılan 180)
ref	string	Hayır	Kendi sipariş / referans numaranız (en fazla 64 karakter). İptalde kullanılabilir.

Response (HTTP 201):

{
  "success": true,
  "message": "Maskeleme kaydı oluşturuldu",
  "data": {
    "id": 12,
    "code": "48213",
    "response": "08501234567,48213",
    "ttl_minutes": 60,
    "expires_at": "2026-10-06 12:00:00"
  }
}

order tipinde response alanı arama dizesidir: numara, virgül (bekle) ve kod. Telefon numarayı arar, bağlantı kurulunca kodu tuşlar.

Request Body (match):

{
  "type": "match",
  "dial_number": "08501234567",
  "gsm": "05321234567",
  "gsm_b": "05339876543"
}

match yanıtında response yalnızca dış hat numarasıdır. Bir cep telefonu aynı dış hat numarasında yalnızca bir aktif eşleşmede olabilir; aksi halde 409 CONFLICT döner.

Request Body (qr):

{
  "type": "qr",
  "dial_number": "08501234567",
  "gsm": "05321234567",
  "ref": "SIP-QR-1001",
  "ttl_minutes": 120
}

qr yanıtında code ve response yerine qr_url döner.

2. Kod ile Sorgula

Tuşlanan koda göre bağlanılacak cep telefonunu (connect_to) döner. Yalnızca order kayıtlarında geçerlidir.

Özellik	Değer
URL	POST /santral/mask/query/code
Auth	Bearer Token

Request Body:

{
  "dial_number": "08501234567",
  "code": "48213"
}

Alan	Tip	Zorunlu	Açıklama
dial_number	string	Evet	Dış hat numaranız
code	string	Evet	Tuşlanan kod

Response:

{
  "success": true,
  "message": "Maskeleme kaydı bulundu",
  "data": {
    "id": 12,
    "type": "order",
    "dial_number": "08501234567",
    "ref": "SIP-1001",
    "code": "48213",
    "connect_to": "05321234567",
    "expires_at": "2026-10-06 12:00:00"
  }
}

3. GSM ile Sorgula

Arayan cep telefonuna göre eşleşmedeki karşı tarafı döner. Yalnızca match kayıtlarında geçerlidir.

Özellik	Değer
URL	POST /santral/mask/query/gsm
Auth	Bearer Token

Request Body:

{
  "dial_number": "08501234567",
  "gsm": "05321234567"
}

Alan	Tip	Zorunlu	Açıklama
dial_number	string	Evet	Dış hat numaranız
gsm	string	Evet	Arayan cep telefonu

Response:

{
  "success": true,
  "message": "Maskeleme kaydı bulundu",
  "data": {
    "id": 13,
    "type": "match",
    "dial_number": "08501234567",
    "ref": null,
    "caller": "05321234567",
    "connect_to": "05339876543",
    "expires_at": "2026-10-06 12:00:00"
  }
}

4. QR ile Sorgula

QR linkine ya da token'a göre kaydı döner.

Özellik	Değer
URL	POST /santral/mask/query/qr
Auth	Bearer Token

Request Body:

{
  "qr": "https:///mask/q/AbC123xYz"
}

Alan	Tip	Zorunlu	Açıklama
qr	string	Evet	qr_url linkinin tamamı ya da yalnızca token

Response:

{
  "success": true,
  "message": "Maskeleme kaydı bulundu",
  "data": {
    "id": 14,
    "type": "qr",
    "dial_number": "08501234567",
    "ref": "SIP-QR-1001",
    "gsm_a": "05321234567",
    "gsm_b": null,
    "call_requested_at": null,
    "expires_at": "2026-10-06 13:00:00"
  }
}

gsm_b ve call_requested_at, karşı taraf henüz "Ara"ya basmadıysa null döner.

5. İptal

id ile tek kaydı ya da ref ile o referanstaki tüm aktif kayıtları kapatır. Örneğin sipariş teslim edildiğinde çağırabilirsiniz.

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

Request Body:

{
  "ref": "SIP-1001"
}

Alan	Tip	Zorunlu	Açıklama
id	number	id ya da ref	Kayıt id'si (oluşturma yanıtındaki id)
ref	string	id ya da ref	Referans numaranız

Response:

{
  "success": true,
  "message": "Maskeleme kaydı iptal edildi",
  "data": {
    "revoked_ids": [
      12
    ]
  }
}

Hata Kodları

Hata yanıtında error alanı aşağıdaki kodlardan birini taşır:

{
  "success": false,
  "message": "Dış hat numarası bu müşteriye ait aktif bir numara değil: 08501234567",
  "error": "NUMBER_NOT_OWNED"
}

HTTP	error	Açıklama
400	MISSING_PARAM	Zorunlu alan eksik
400	INVALID_PARAM	Geçersiz değer (ör. bilinmeyen type)
400	INVALID_JSON	Gövde geçerli bir JSON nesnesi değil
400	INVALID_GSM	Geçersiz cep telefonu ya da gsm ile gsm_b aynı
400	INVALID_CODE / INVALID_CODE_LENGTH	Kod rakam değil ya da 4-6 hane dışında
400	INVALID_TTL	ttl_minutes 1-1440 dışında
401	UNAUTHORIZED	Geçersiz API anahtarı ya da yetki yok
403	NUMBER_NOT_OWNED	dial_number size ait aktif bir numara değil
404	NOT_FOUND	Aktif kayıt bulunamadı
409	CONFLICT	Aynı kod ya da cep telefonu zaten aktif bir kayıtta
502	UPSTREAM_ERROR	Maskeleme servisine ulaşılamadı, tekrar deneyin

Hızlı Kullanım: Kayıt Oluşturmadan Maskeli Çağrı​

Maskeleme Tipleri​

Kimlik Doğrulama​

Genel Kurallar​

Endpointler​

1. Kayıt Oluştur​

2. Kod ile Sorgula​

3. GSM ile Sorgula​

4. QR ile Sorgula​

5. İptal​

Hata Kodları​

Hızlı Kullanım: Kayıt Oluşturmadan Maskeli Çağrı

Maskeleme Tipleri

Kimlik Doğrulama

Genel Kurallar

Endpointler

1. Kayıt Oluştur

2. Kod ile Sorgula

3. GSM ile Sorgula

4. QR ile Sorgula

5. İptal

Hata Kodları