SMS API Dökümantasyonu

Güvenli toplu SMS, OTP ve raporlama işlemleri için JSON tabanlı REST API.
API Version: v1
Content-Type: application/json
POST /api/send_sms.php

POST /api/get_balance.php

POST /api/send_otp.php

POST /api/get_report.php
📌Ortak Kurallar

🔐 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 45000 adet numara gönderilebilir.

🚀1. Toplu SMS Gönderme – POST /api/send_sms.php

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 45000 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
  }
}
🔑2. OTP Mesaj Gönderme – POST /api/send_otp.php

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."
}
💳3. Bakiye Sorgulama – POST /api/get_balance.php

Müşterinin mevcut SMS kredisini (bakiye) döndürür.

URL: /api/get_balance.php

Method: POST

Content-Type: application/json

📥 Örnek İstek (Request Body)

{
  "api_key": "MUSTERI_API_HASH"
}

✅ Başarılı Cevap

{
  "success": true,
  "credit": 12345
}
📊4. Rapor Sorgulama – POST /api/get_report.php

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
}

📥 Queue ID ile Detay Liste (Tüm Numaralar) Örneği

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

Sayfalı Detay Liste (Opsiyonel)

{
  "api_key": "MUSTERI_API_HASH",
  "queue_id": 10405,
  "detail": true,
  "limit": 1000,
  "offset": 0
}

📥 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.
detail bool opsiyonel true ise kuyruk altındaki numaraları tek tek listeler. Varsayılan olarak numara başına en güncel kayıt döner (duplicate olmaz).
history bool opsiyonel Sadece detail: true modunda geçerli. true ise aynı numara için geçmiş satırlar (duplicate) da dönebilir.
limit int opsiyonel Detay listede sayfa boyutu. Gönderilmezse sistem offset'ten itibaren mümkünse tümünü döndürür. Üst sınır: 45000.
offset int opsiyonel Detay listede başlangıç kaydı.

✅ 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"
  },
  "mode": "summary",
  "detail": [
    {
      "status": "DELIVERED",
      "adet": "91"
    },
    {
      "status": "FAILED",
      "adet": "2"
    },
    {
      "status": "PENDING",
      "adet": "4"
    }
  ],
  "filter": {
    "number": null,
    "detail": false,
    "history": false,
    "limit": 0,
    "offset": 0
  }
}

✅ 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"
  },
  "mode": "single",
  "detail": [
    {
      "status": "DELIVERED",
      "sentdate": "2025-12-03 20:47:34",
      "networkid": null
    }
  ],
  "filter": {
    "number": "5051234567",
    "detail": false,
    "history": false,
    "limit": 0,
    "offset": 0
  }
}

✅ Başarılı Cevap – Detay Liste (Queue ID)

{
  "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"
  },
  "mode": "detail",
  "detail": [
    {
      "number": "5051234567",
      "status": "DELIVERED",
      "sentdate": "2025-12-03 20:47:34",
      "networkid": null
    }
  ],
  "page": {
    "limit": 1000,
    "offset": 0,
    "total": 97,
    "truncated": false
  },
  "filter": {
    "number": null,
    "detail": true,
    "history": false,
    "limit": 1000,
    "offset": 0
  }
}

📡 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."
}
SMS API • Bu doküman örnek amaçlıdır, gerçek alan adları ve URL'ler proje yapınıza göre düzenlenmelidir.