SMS API Dökümantasyonu

🔐 Kimlik Doğrulama

Kural	Açıklama
api_key zorunlu	Tüm isteklerde body içinde gönderilmelidir.
Değer kaynağı	musteriler.api_hash alanındaki değer kullanılmalıdır.
API durumu	api_durum = 'aktif' olmalıdır.
IP kısıtlaması	api_ip_kisitlama = 'aktif' ise, istek yapan IP izinli IP listesinde olmalıdır.

💳 Kredi Kullanımı

Alan	Açıklama
Kredi alanı	musteriler.orjinli alanında tutulur.
SMS başına tüketim	1 SMS = 1 kredi olarak düşülür (bu API sadece kuyruğa yazar, fiili düşüm mevcut sisteminizde yapılır).

📱 Numara Formatı

Sadece Türkiye GSM numaraları kabul edilir. Kabul edilen formatlar:

• 5XXXXXXXXX
• 05XXXXXXXXX
• +905XXXXXXXXX

Sistem tüm numaraları içerde 5XXXXXXXXX formatına normalize eder.

💬 Mesaj Kuralları

Özellik	Limit / Kural
Maksimum uzunluk	En fazla 160 karakter.
Karakter seti	Türkçe karakterler (latin + çÇğĞıİöÖşŞüÜ), rakamlar ve temel noktalama işaretleri.
Çift tırnak	" kullanılabilir.
Yeni satır	Alt satıra geçmek için \n kullanılabilir.
Yasak karakterler	₺ ve benzeri özel Unicode karakterler kabul edilmez.

📦 Adet Limiti

Tek istekte en fazla 100000 adet numara gönderilebilir.

URL: /api/send_sms.php

Method: POST

Content-Type: application/json

📥 Örnek İstek (Request Body)

{
  "api_key": "MUSTERI_API_HASH",
  "title": "NUMARALI",
  "message": "Merhaba, bu bir test mesajıdır",
  "numbers": [
    "5051234567",
    "05321234567",
    "+905551234567"
  ]
}

🔎 Alanlar

Alan	Tip	Zorunlu	Açıklama
api_key	string	zorunlu	Müşteriye ait musteriler.api_hash değeri.
title	string	zorunlu	Gönderim başlığı (ör: NUMARALI). İlgili müşteri ve bayi için aktif olmalıdır.
message	string	zorunlu	SMS metni. Maksimum 160 karakter, sadece izin verilen karakterler.
numbers	array<string> / string	zorunlu	Türkiye GSM numaraları listesi. Tek istekte maksimum 100000 adet. Virgülle ayrılmış string de olabilir.

✅ Başarılı Cevap (Response)

{
  "success": true,
  "queue_id": 10405,
  "accepted": {
    "count": 3,
    "numbers": [
      "5051234567",
      "5321234567",
      "5551234567"
    ]
  },
  "invalid": {
    "count": 1,
    "numbers": [
      "12345"
    ]
  }
}

• queue_id: Bu ID üzerinden rapor sorgulaması yapılabilir.
• accepted.numbers: Normalize edilmiş, geçerli numaralar (5XXXXXXXXX formatında).
• invalid.numbers: Formatı hatalı / kabul edilmeyen numaralar.

❌ Hata Örnekleri

Geçersiz JSON

{
  "success": false,
  "error": "GEÇERSİZ_JSON",
  "message": "Geçerli bir JSON body gönderilmelidir."
}

Yetersiz kredi

{
  "success": false,
  "error": "YETERSIZ_KREDI",
  "message": "Hesabınızda yeterli SMS kredisi bulunmamaktadır.",
  "detail": {
    "kredi": 10,
    "istenen_adet": 15
  }
}

Tek bir numaraya OTP (tek kullanımlık kod) gönderir.

URL: /api/send_otp.php

Method: POST

Content-Type: application/json

📥 Örnek İstek (Request Body)

{
  "api_key": "MUSTERI_API_HASH",
  "title": "NUMARALI",
  "number": "5051234567",
  "code_length": 6
}

🔎 Alanlar

Alan	Tip	Zorunlu	Açıklama
api_key	string	zorunlu	Kimlik doğrulama anahtarı.
title	string	zorunlu	Gönderim başlığı.
number	string	zorunlu	Türkiye GSM numarası.
code_length	int	opsiyonel	4 ile 8 arasında olmalıdır, aksi durumda 6 olarak kabul edilir.

Not: Mesaj metni otomatik olarak sistem tarafından rastgele seçilen şablonlardan biri ile oluşturulur. Kullanıcı mesaj metni gönderemez.

✅ Başarılı Cevap

{
  "success": true,
  "queue_id": 10406,
  "number": "5051234567",
  "code": "123456"
}

• queue_id: Kuyruk kaydı ID'si.
• code: Üretilen OTP kodu (kendi sisteminizde oturum/veritabanı vb. yerde saklayabilirsiniz).

❌ Hata Örneği

Eksik alan:

{
  "success": false,
  "error": "EKSİK_PARAMETRE",
  "message": "api_key, title ve number alanları zorunludur."
}

kuyruk tablosuna yazılan gönderimler için toplu veya tek numara bazlı rapor döner.

URL: /api/get_report.php

Method: POST

Content-Type: application/json

📥 Toplu Özet Rapor Örneği

{
  "api_key": "MUSTERI_API_HASH",
  "queue_id": 10405
}

📥 Tek Numara Bazlı Rapor Örneği

{
  "api_key": "MUSTERI_API_HASH",
  "queue_id": 10405,
  "number": "5051234567"
}

🔎 Alanlar

Alan	Tip	Zorunlu	Açıklama
api_key	string	zorunlu	Kimlik doğrulama anahtarı.
queue_id	int	zorunlu	Raporu istenen kuyruk kaydı.
number	string	opsiyonel	Belirli bir numaranın raporunu görmek için.

✅ Başarılı Cevap – Özet Rapor

{
  "success": true,
  "queue": {
    "id": 10405,
    "date": "2025-12-03 22:09:00",
    "count": 97,
    "delivered": 91,
    "pending": 4,
    "failed": 2,
    "title": "NUMARALI",
    "type": 100,
    "group": "api_6570fe...",
    "status": "4"
  },
  "detail": [
    {
      "status": "DELIVERED",
      "adet": "91"
    },
    {
      "status": "FAILED",
      "adet": "2"
    },
    {
      "status": "PENDING",
      "adet": "4"
    }
  ],
  "filter": {
    "number": null
  }
}

✅ Başarılı Cevap – Tek Numara Raporu

{
  "success": true,
  "queue": {
    "id": 10405,
    "date": "2025-12-03 22:09:00",
    "count": 97,
    "delivered": 91,
    "pending": 4,
    "failed": 2,
    "title": "NUMARALI",
    "type": 100,
    "group": "api_6570fe...",
    "status": "4"
  },
  "detail": [
    {
      "status": "DELIVERED",
      "sentdate": "2025-12-03 20:47:34",
      "networkid": null
    }
  ],
  "filter": {
    "number": "5051234567"
  }
}

📡 Status Türleri

Status	Açıklama
DELIVERED	Mesaj başarıyla teslim edilmiştir.
FAILED	Mesaj gönderimi sırasında hata oluşmuştur.
PENDING	Mesaj henüz operatör/hat üzerinde sonuçlanmamıştır.

❌ Hata Örnekleri

Kuyruk kaydı bulunamazsa:

{
  "success": false,
  "error": "KAYIT_YOK",
  "message": "Belirtilen queue_id için kuyruk kaydı bulunamadı."
}

Kuyruk farklı bir müşteriye aitse:

{
  "success": false,
  "error": "ERISIM_YOK",
  "message": "Bu kuyruk kaydına erişim yetkiniz yok."
}