SMS API entegrasyonu: tekrar, durum ve webhook'u doğru kurmak

Sipariş sisteminize, randevu yazılımınıza ya da CRM'inize SMS eklemek ilk bakışta beş dakikalık iştir: bir adrese numara ve metin gönderirsiniz. Ama canlıda iş başka sorulara döner: istek zaman aşımına uğradıysa ileti gitti mi? Müşteri iki SMS aldı mı? "Gönderildi" ile "iletildi" aynı şey mi?

1. En basit istek

Mesajra'da anahtarınızı panelde oluşturur, isteği Bearer başlığıyla gönderirsiniz:

curl -X POST https://mesajra.tanitek.com.tr/api/v1/mesajlar \
  -H "Authorization: Bearer mk_..." -H "Content-Type: application/json" \
  -d '{"alici":"05321112233","metin":"Siparişiniz yola çıktı"}'

Yanıt 201 ile iletinin kimliği ve durumu döner: KUYRUKTA. Bu, iletinin gönderildiği anlamına gelmez; sunucudaki kuyruğa yazıldığı anlamına gelir. Telefon iletiyi alıp kendi hattından gönderdiğinde durum ilerler.

2. Tekrar güvenli gönderim: disKimlik

Ağ isteği zaman aşımına uğradığında yazılımınız ne yapmalı? Yeniden denerse ve ilk istek aslında ulaşmışsa müşteri iki SMS alır. Denemezse ileti hiç gitmemiş olabilir.

Çözüm, her iletiye kendi sisteminizdeki benzersiz bir kimlik vermektir. Mesajra'da bu alan disKimlik'tir (İngilizce externalId). Aynı değerle gelen ikinci istek yeni ileti açmaz, ilk iletiyi döndürür. Böylece gönül rahatlığıyla yeniden deneyebilirsiniz.

{
  "alici": "05321112233",
  "metin": "Siparişiniz kargoya verildi. Takip no: 7731",
  "disKimlik": "siparis-1042-kargo"
}

Kimliği iş olayından türetin: "siparis-1042" değil, "siparis-1042-kargo". Aynı sipariş için ileride "teslim edildi" iletisi de göndereceksiniz.

3. Durumları doğru okuyun

Bir ileti şu yolu izler: KUYRUKTA → ATANDI (telefon aldı) → GONDERILIYOR → GONDERILDI (operatöre çıktı) → ILETILDI (alıcının telefonuna ulaştı, teslim raporu). Yan dallar BASARISIZ ve IPTAL'dir.

GONDERILDI ≠ ILETILDI. Alıcının telefonu kapalıysa ileti operatörde bekler; teslim raporu sonra gelir ya da hiç gelmez.
IPTAL ve RET_LISTESI. Alıcı daha önce "İPTAL" yazdıysa ileti hiç gönderilmez ve hataKodu: RET_LISTESI ile iptal edilir. Bu bir hata değil, doğru davranıştır.
Durum yalnız ileri gider. Geç gelen eski bir rapor durumu geri almaz; sisteminizde de aynı kuralı uygulayın.

Tek iletiyi kendi kimliğinizle sorgulayabilirsiniz: GET /mesajlar/dis/siparis-1042-kargo.

4. Sorgulamak yerine dinleyin: webhook

Binlerce iletinin durumunu tek tek sorgulamak yerine webhook kurun. Panelden bir adres ve olaylar seçersiniz (ileti.gonderildi, ileti.iletildi, ileti.basarisiz, gelen.sms, cihaz.cevrimdisi); olay olduğu anda adresinize POST gelir.

Webhook adresiniz herkese açıktır; gelen isteğin gerçekten Mesajra'dan geldiğini doğrulamalısınız. Her istekte X-Mesajra-Zaman ve X-Mesajra-Imza başlıkları bulunur. İmza, zaman ve ham gövdenin HMAC-SHA256 özetidir:

import hmac, hashlib, time

def dogrula(govde: bytes, zaman: str, imza: str, gizli: str) -> bool:
    if abs(time.time() - int(zaman)) > 300:   # eski isteği tekrar oynatmaya karşı
        return False
    beklenen = "sha256=" + hmac.new(gizli.encode(), f"{zaman}.".encode() + govde, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, imza)

İmzayı ham gövde üzerinden hesaplayın; JSON'u ayrıştırıp yeniden yazarsanız boşluklar değişir, imza tutmaz.
Karşılaştırmayı sabit zamanlı yapın (compare_digest, hash_equals, timingSafeEqual).
Hızlı yanıt verin (2xx), işi kendi kuyruğunuza bırakın. 2xx dışı yanıtta istek 1, 5, 30, 120 ve 720 dakika sonra yeniden gelir; aynı olayı iki kez işlemeyecek şekilde ileti kimliğine göre davranın.

5. Gelen SMS'leri de alın

Müşteriler SMS'e yanıt verir: "Teşekkürler", "Saati değiştirebilir miyiz?", "İPTAL". gelen.sms olayını dinleyerek ya da GET /gelen?sonraki=<id> ile kaldığınız yerden okuyarak bu yanıtları destek sisteminize düşürebilirsiniz.

6. Hataları sınıflandırın

400 doğrulama hatasıdır; yeniden denemeyin, veriyi düzeltin.
401 / 403 anahtar, IP kısıtı ya da planla ilgilidir; yeniden denemek işe yaramaz.
402 abonelik kilitlidir; yöneticinize haber verin.
409 TEKRAR aynı alıcıya aynı metnin kısa sürede ikinci kez gönderildiğini söyler; disKimlik kullanıyorsanız bunu görmezsiniz.
429 aylık hak doldu (KOTA_DOLDU) ya da dakika sınırı aşıldı (HIZ_SINIRI); ikincisinde bekleyip yeniden deneyin.

Eski sistemler için

JSON gönderemeyen eski bir sistemle çalışıyorsanız GET /gonder?anahtar=…&alici=…&metin=… kısa yolu vardır. Anahtar adreste gittiği için yalnız HTTPS üzerinden ve sunucudan sunucuya kullanın; tarayıcıda çalışan koda koymayın.

Bütün uçlar ve PHP, Python, curl örnekleri geliştiriciler sayfasında.