NetGSM REST API ve sessiz başarısızlıklar

İstek

REST uç noktası JSON gövde ve temel kimlik doğrulama bekler. En küçük çalışan örnek:

<?php
$payload = [
  'msgheader' => 'ONAYLI_BASLIK',
  'encoding'  => 'TR',
  'messages'  => [
    ['msg' => 'Kaydınız alınmıştır.', 'no' => '5301234567'],
  ],
];

$ch = curl_init('https://api.netgsm.com.tr/sms/rest/v2/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
  CURLOPT_USERPWD        => NETGSM_USER . ':' . NETGSM_PASS,
  CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
  CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

JSON_UNESCAPED_UNICODE bayrağı önemlidir; Türkçe karakterlerin \u011f gibi kaçış dizileriyle gönderilmesi bazı kurulumlarda sorun çıkarır.

Cevap kodları

Buradaki kritik nokta şudur: $http değeri neredeyse her zaman 200'dür. Gerçek sonuç gövdededir.

00	Başarılı — gönderim kuyruğa alındı
20	Mesaj metni hatalı ya da karakter sınırı aşıldı
30	Kullanıcı adı/parola yanlış veya API erişimi IP ile kısıtlı
40	Gönderici başlığı onaylı değil
50	İYS kaynaklı engel — alıcı ticari ileti almıyor
70	Hatalı parametre; gövde yapısı beklenenden farklı

30 kodu en çok zaman kaybettirenidir, çünkü kimlik bilgileri doğru olsa bile alınır. NetGSM hesabında API erişimi belirli IP adreslerine kısıtlanabilir; geliştirme makinenizden çalışan kod, sunucuya taşındığında bu yüzden durur. Sunucunun çıkış IP'sini panele eklemeden test etmek zaman kaybıdır.

Numara biçimi

Servis numarayı 5XXXXXXXXX biçiminde bekler: on hane, başta sıfır yok, ülke kodu yok. Gerçek hayatta veritabanınızdaki numaralar bu kadar düzenli olmaz — kullanıcılar boşluk, parantez, tire, +90 ve başta sıfır yazar.

Gönderimden önce tek bir normalleştirme adımı, hataların büyük kısmını ortadan kaldırır:

function netgsm_no(string $raw): ?string {
    $d = preg_replace('/\D+/', '', $raw);        // rakam dışını at
    if (str_starts_with($d, '90'))  $d = substr($d, 2);
    if (str_starts_with($d, '0'))   $d = substr($d, 1);
    return preg_match('/^5\d{9}$/', $d) ? $d : null;
}

Geçersiz numarayı göndermek yerine null döndürüp kaydetmek, hem kredi israfını hem de teşhis edilemeyen başarısızlıkları önler.

Türkçe karakter

Burada bir ödünleşme vardır. encoding değerini TR yaparsanız Türkçe harfler doğru görünür, ama mesaj Unicode olarak kodlanır ve tek SMS 160 değil 70 karaktere düşer. Uzun metin birden fazla krediye bölünür.

Alternatif, metni ASCII'ye indirgemektir: ş→s, ğ→g, ı→i, ö→o, ü→u, ç→c. 160 karakter korunur ama okunuş bozulur. Karar içeriğe bağlıdır: doğrulama kodu ve randevu hatırlatması için ASCII yeterlidir; kurumsal bilgilendirmede Türkçe karakter değerlidir.

Hangisini seçerseniz seçin, gönderimden önce karakter sayısını hesaplayın ve kaç krediye bölüneceğini kaydedin. Aksi hâlde aylık fatura beklenmedik çıkar.

İYS

Türkiye'de ticari elektronik ileti göndermek İleti Yönetim Sistemi'ne kayıtlı onaya bağlıdır. Bilgilendirme amaçlı mesajlar — sipariş durumu, randevu hatırlatma, doğrulama kodu — bu kapsamın dışındadır; kampanya ve tanıtım içerikleri ise kapsam içindedir.

Ayrımı kod tarafında da yapın: ticari gönderimlerde İYS kontrolü uygulayın, işlemsel gönderimlerde uygulamayın. İkisini tek bir fonksiyondan geçirmek, ya işlemsel mesajların gereksiz yere engellenmesine ya da ticari mesajların mevzuata aykırı gitmesine yol açar.

Sağlam entegrasyon

Üretime çıkacak bir SMS katmanının karşılaması gereken asgari maddeler:

• Gövdedeki kodu okuyun, HTTP durumuna güvenmeyin
• Her gönderimi kaydedin: numara, metin, dönen kod, zaman damgası
• Zaman aşımı verin (CURLOPT_TIMEOUT) — SMS servisi yavaşladığında ödeme akışınız kilitlenmesin
• Gönderimi kullanıcının isteğinden ayırın; kuyruğa alın, arka planda gönderin
• Numarayı gönderim öncesi normalleştirin ve doğrulayın
• Kimlik bilgilerini koda gömmeyin; ortam değişkeninde tutun

Kayıt tutmak özellikle önemlidir. "SMS gelmedi" şikâyeti geldiğinde, dönen kodu görebiliyorsanız sorunu saniyeler içinde ayırırsınız: 00 ise mesaj operatöre teslim edilmiştir ve sorun operatör tarafındadır; 40 ise başlık onayı düşmüştür; kayıt yoksa gönderim hiç denenmemiştir.

Özet

SMS entegrasyonları basit görünür ve tam da bu yüzden özensiz yazılır. Kritik alışkanlık tek cümlede toplanır: taşıyıcının HTTP cevabı, iş sonucunu göstermez. Gövdedeki kodu okuyun, her gönderimi kaydedin, numarayı normalleştirin ve gönderimi ana akıştan ayırın. Bu dört madde, SMS kaynaklı hata ayıklama süresinin neredeyse tamamını ortadan kaldırır.