MASKSMS API v1

Uygulamanı bağla

Geliştirici merkezinden anahtar oluştur, izinlerini seç ve hesabına ait siparişleri kendi uygulamandan takip et.

Kimlik doğrulama

Authorization: Bearer $MASKSMS_API_KEY

Anahtar yalnızca oluşturulduğunda gösterilir. read okuma, order sipariş oluşturma, SMS sorgulama ve iptal iznidir. Sipariş izni hesabının bakiyesini kullanır. Anahtarlar yönetim yetkisi vermez.

Uç noktalar

GET  /api/v1/catalog
GET  /api/v1/countries?productId=migros-2346
GET  /api/v1/balance
GET  /api/v1/orders
GET  /api/v1/orders/{id}
POST /api/v1/orders
POST /api/v1/orders/{id}/poll
POST /api/v1/orders/{id}/cancel

Bakiye yanıtı

{ "balanceMinor": 1250, "currency": "USD" }

Bu örnekte bakiye 12,50 USD’dir. Tutarlar integer cent olarak döner. Bağlantıyı önce GET /api/v1/balance ile test et; sipariş oluşturmak gerekmez.

Özel Sites yayınına dış sunucudan bağlanırken barındırma erişimi ayrıca gereklidir. Sites servis erişim anahtarı sadece site sahibinin sunucusunda tutulur; müşterilerle paylaşılmaz. Geliştirici merkezindeki bağlantı kontrolü tarayıcı oturumu içinde çalışır.

Numara siparişi

curl -X POST https://masksms.com/api/v1/orders \
  -H "Authorization: Bearer $MASKSMS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"productId":"migros-2346","countryCode":"tr","idempotencyKey":"siparis-0001"}'

Ürün ve ülke güncel katalog ve stoktan seçilir. Aynı isteğin tekrarında aynı idempotencyKey kullanılmalı; zaman aşımından sonra yeni anahtarla otomatik sipariş verilmemeli. SMS kontrolünü 15 saniyeden sık yapma. Sonuçlar: waiting, completed, cancelled, expired, failed, review.

Ülkeye göre fiyat ve kiralama

Ülke kodlarını API’nin döndürdüğü biçimde kullan. Seçilen ülkenin priceMinor tutarını siparişte expectedPriceMinor olarak gönder. Fiyat değişirse tahsilat öncesi 409 döner. requiresQuote: true olan ülkenin fiyatı ve stoğu henüz doğrulanmamıştır; aynı ülke uç noktasına countryCode ekleyerek güncel teklif al.

rental: true ürünleri peşin ücretli kiralamadır ve siparişte rentalTermsAccepted: true onayı gerekir. İlk SMS kiralamayı bitirmez. Erken kapatma iadesizdir; 20 dakika aktivasyon iadesi kiralamalara uygulanmaz. Sonraki mesajları sorgulayarak takip et; her kiralama mesajı için ayrı webhook gönderilmez.

Hata ve sınırlar

Geçersiz/iptal anahtar: 401. Eksik yetki: 403. Yetersiz müşteri bakiyesi: 402. Durum veya stok değişikliği: 409. İstek sınırı: 429. Anahtar başına dakikada 120 istek, ayrıca sipariş ve SMS sorgu sınırları uygulanır. Tutarlar USD cent cinsindedir.

İmzalı webhook

Geliştirici merkezinde HTTPS alıcı adresini ve olayları seç. Adresin alan adı yönetici tarafından sunucudaki izin listesine eklenmiş olmalı. İmza anahtarı bir kez gösterilir; sonrasında şifrelenerek saklanır. Test olayı gönderebilir, teslim geçmişini görebilir ve başarısız teslimleri yeniden kuyruğa alabilirsin.

X-Relay-Event-ID: benzersiz-olay
X-Relay-Timestamp: Unix-saniye
X-Relay-Signature: sha256=HMAC_SHA256(secret, timestamp + '.' + rawBody)

İmzayı ham gövdeyle sabit sürede karşılaştır, zaman farkını kontrol et ve olay kimliğini tekil sakla. Aynı olay tekrar gelebilir. Başarılı kabul için 2xx yanıt ver; yönlendirmeler takip edilmez. Başarısız teslimler 30 saniyeden başlayarak en fazla 8 kez denenir.

Olaylar

order.created, order.waiting, order.completed, order.refunded, order.review, payment.approved, webhook.test.

Örnek imza doğrulama kodu kaynak paketindeki docs/developer-api.md dosyasında bulunur.