SMS

1.6k görüntülenme Markdown

Toplu mesaj gönderimini fiyatlandıran, yapan ve geçmişini veren beş uç.

Genel Bakış

Müşteri kendi cüzdanından ödeyerek toplu mesaj gönderebilir. Akış üç adımdır: bir başlık seçin, fiyat alın, gönderin.

Fiyat hedef ülkeye ve mesajın parça sayısına göre değişir. Metin uzadıkça ya da alfabe dışına çıktıkça parça sayısı artar ve tutar onunla birlikte büyür.

Bazı ülkeler başlığın önceden kayıtlı olmasını ister. Kaydı olmayan bir ülkeye giden numaralar sessizce düşmez: elenenler listesinde gerekçesiyle görünür.

Referans

Başlıkları Listeleme

get/api/v1/client/sms/senders
Sms/GetSmsSenders anahtarın sahibi

Gönderimde kullanılabilecek başlıkları ve ülke kayıtlarını döndürür.

Dönen alanlar data[] — 4
idintBaşlığın numarası.
namestringAlıcının göreceği metin. Gönderim ucuna bu değer verilir.
is_defaultboolHesabın varsayılan başlığı mı.
countriesobject[]Ön kayıt gerektiren ülkelerdeki durum. Ülke kodu ve durum taşır; ön kayıt istemeyen ülkeler burada görünmez.
Hatalar 3
sms_disabled422Operatör uluslararası mesaj hizmetini kapatmış.
sms_api_disabled422Operatör mesaj arayüzünü kapatmış. Panel çalışmaya devam eder.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/client/sms/senders' \
  -H "Authorization: Bearer $CLIENT_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/client/sms/senders', {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data } = await res.json();
const preferred = data.find((s) => s.is_default) ?? data[0];
$ch = curl_init('https://panel.ornek.com/api/v1/client/sms/senders');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Bos ulke listesi ENGEL DEGILDIR: cogu ulke on kayit istemez ve baslik oralarda dogrudan calisir.
$senders = Kernel::internal('client:Sms/GetSmsSenders', ['owner_id' => $uid])['data'];
$name = $senders[0]['name'] ?? null;

Fiyat Alma

post/api/v1/client/sms/quote
Sms/QuoteSms gönderim yok

Gönderimin ne kadar tutacağını ve neyin eleneceğini söyler.

Gövde 3
senderstringreqGönderen başlığı. Hesabın etkin başlıklarından biri olmalıdır.
messagestringreqMesaj metni. Parça tavanını aşan metin kırpılır ve kırpıldığı bildirilir.
numbersarrayreqAlıcı numaralar. Uluslararası biçimde; tek bir metin olarak gönderilirse satır, virgül ve noktalı virgülden bölünür.
Dönen alanlar data — 6
messageobjectMetin çözümlemesi. Kodlama, uzunluk, parça sayısı, kırpılıp kırpılmadığı ve gerçekten gidecek metin.
recipientsintÜcretlendirilip gönderilecek numara sayısı.
total_partsintToplam parça. Faturalama birimi budur.
totalobjectGönderim ucunun keseceği tutar.
countriesobject[]Hedef ülke başına kırılım. Kod, ad, adet, parça, birim fiyat ve toplam.
skippedobjectElenenler. Sayı, çözülemeyen girdiler, fiyatlanmayan ülkeler ve başlığın kaydı olmayan ülkeler.
Hatalar 6
sms_disabled422Operatör uluslararası mesaj hizmetini kapatmış.
sms_api_disabled422Operatör mesaj arayüzünü kapatmış. Panel çalışmaya devam eder.
sender_invalid422Başlık eksik, size ait değil ya da etkin değil.
message_required422Mesaj boş.
numbers_required422Alıcı listesi boş.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/client/sms/quote' \
  -H "Authorization: Bearer $CLIENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sender":"TESTBRAND","message":"Your code is 482913","numbers":["+15551112233"]}'
const res = await fetch('https://panel.ornek.com/api/v1/client/sms/quote', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${clientKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ sender, message, numbers }),
});

const { data } = await res.json();
if (data.skipped.total) reviewSkipped(data.skipped);
$ch = curl_init('https://panel.ornek.com/api/v1/client/sms/quote');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $clientKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(compact('sender', 'message', 'numbers')),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Elenen hedefler HATA DEGIL: teklif her zaman basarili doner, kaybi skipped blogundan okuyun.
$q = Kernel::internal('client:Sms/QuoteSms',
    ['owner_id' => $uid, 'sender' => $sender, 'message' => $text, 'numbers' => $nums])['data'];

$willCost = $q['total']['amount'];
$willDrop = $q['skipped']['total'];

Toplu Gönderim

post/api/v1/client/sms/send
Sms/SendSms cüzdandan keser

Mesajı gönderir ve tutarı cüzdandan keser.

Gövde 3
senderstringreqGönderen başlığı. Hesabın etkin başlıklarından biri olmalıdır.
messagestringreqMesaj metni. Parça tavanını aşan metin kırpılır ve kırpıldığı bildirilir.
numbersarrayreqAlıcı numaralar. Uluslararası biçimde; tek bir metin olarak gönderilirse satır, virgül ve noktalı virgülden bölünür.
Dönen alanlar 201 — data — 9
message_idintGönderimin numarası. Geçmiş ucunda bu numarayla aranır.
senderstringKullanılan başlık.
acceptedintÜcretlendirilip sağlayıcıya verilen alıcı sayısı.
partsintMesaj başına parça.
total_partsintToplam parça.
totalobjectCüzdandan kesilen tutar.
balanceobjectKesim sonrası cüzdan.
report_idstringSağlayıcının parti referansı.
skippedobjectElenenler. Sayı, çözülemeyen girdiler, fiyatlanmayan ülkeler ve başlığın kaydı olmayan ülkeler.
Hatalar 10
sms_disabled422Operatör uluslararası mesaj hizmetini kapatmış.
sms_api_disabled422Operatör mesaj arayüzünü kapatmış. Panel çalışmaya devam eder.
sender_invalid422Başlık eksik, size ait değil ya da etkin değil.
no_recipients422Bütün numaralar elendi. Gerekçe yanıtın ayrıntısında gelir.
price_unavailable422Tutar sıfıra fiyatlandı.
send_rejected422Bir kanca gönderimi reddetti.
sms_module_unavailable422Yapılandırılmış bir gönderim sağlayıcısı yok.
insufficient_balance422Cüzdan tutarı karşılamıyor. Hiçbir şey gönderilmez ve kesilmez.
send_failed500Sağlayıcı gönderimi reddetti. Kesilen tutar tamamen iade edilir.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/client/sms/send' \
  -H "Authorization: Bearer $CLIENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sender":"TESTBRAND","message":"Your code is 482913","numbers":["+15551112233"]}'
const res = await fetch('https://panel.ornek.com/api/v1/client/sms/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${clientKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ sender, message, numbers }),
});

const { data } = await res.json();
console.log(data.accepted, data.total, data.balance);
$ch = curl_init('https://panel.ornek.com/api/v1/client/sms/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $clientKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(compact('sender', 'message', 'numbers')),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Tutari SUNUCU yeniden hesaplar: teklifte gordugunuz rakam bir soz degil, gonderim kendi fiyatini bilir.
$r = Kernel::internal('client:Sms/SendSms',
    ['owner_id' => $uid, 'sender' => $sender, 'message' => $text, 'numbers' => $nums])['data'];

$charged = $r['total']['amount'];

Gönderim Geçmişi

get/api/v1/client/sms/messages
Sms/GetSmsMessages anahtarın sahibi

Yapılmış gönderimleri en yeniden başlayarak döndürür.

Sorgu 2
pageintKaçıncı sayfa.
limitintSayfa başına satır. En çok 100.
Dönen alanlar data[] — 9 + meta — 4
message_idintGönderimin numarası.
senderstringKullanılan başlık.
textstringGönderilen metin.
recipientsintÜcretlendirilen alıcı sayısı.
partsintMesaj başına parça.
total_partsintToplam parça.
totalobjectKesilen tutar.
countriesobject[]Hedef ülke kırılımı.
created_atstringGönderim anı.
total_countintToplam gönderim. Meta altında toplam adıyla döner.
pageintBulunulan sayfa.
limitintSayfa boyutu.
next_pageintSonraki sayfa.
Hatalar 3
sms_disabled422Operatör uluslararası mesaj hizmetini kapatmış.
sms_api_disabled422Operatör mesaj arayüzünü kapatmış. Panel çalışmaya devam eder.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/client/sms/messages' \
  -H "Authorization: Bearer $CLIENT_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/client/sms/messages', {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data, meta } = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/client/sms/messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Gecmiste ALICI NUMARALARI yoktur: numaralar yalniz tek gonderim ucunda gelir.
$rows = Kernel::internal('client:Sms/GetSmsMessages', ['owner_id' => $uid])['data'];
$one  = Kernel::internal('client:Sms/GetSmsMessage',
    ['owner_id' => $uid, 'id' => $rows[0]['message_id']])['data'];

Tek Gönderimi Okuma

get/api/v1/client/sms/messages/{id}
Sms/GetSmsMessage anahtarın sahibi

Bir gönderimi alıcı numaralarıyla birlikte döndürür.

Dönen alanlar data — 11
dataobjectGeçmiş satırının alanları.
numbersstring[]Ücretlendirilip gönderilen numaralar.
report_idstringSağlayıcının parti referansı.
Hatalar 4
not_found404Böyle bir gönderim yok ya da başka bir müşteriye ait.
sms_disabled422Operatör uluslararası mesaj hizmetini kapatmış.
sms_api_disabled422Operatör mesaj arayüzünü kapatmış. Panel çalışmaya devam eder.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/client/sms/messages/4520' \
  -H "Authorization: Bearer $CLIENT_KEY"
const res = await fetch(`https://panel.ornek.com/api/v1/client/sms/messages/${id}`, {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data } = await res.json();
console.log(data.numbers.length, data.report_id);
$ch = curl_init('https://panel.ornek.com/api/v1/client/sms/messages/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Alici bazli TESLIM RAPORU burada YOK: saglayici-canli rapor panel gorunumunde kalir.
$m = Kernel::internal('client:Sms/GetSmsMessage', ['owner_id' => $uid, 'id' => $id])['data'];
$sentTo = $m['numbers'];

Tuzaklar

Elenen alıcılar hata döndürmez

Fiyat ve gönderim uçları geçersiz numaraları, fiyatlanmamış ülkeleri ve başlığın kaydı olmayan ülkeleri sessizce elemez, ama gönderimi de durdurmaz: kalan küme gider ve elenenler yanıtta listelenir. Bu bloğu okumazsanız mesajın bir bölümünün hiç gitmediğini fark etmezsiniz.

Teklif bir söz değildir

Gönderim ucu tutarı kendisi yeniden hesaplar ve istemcinin gönderdiği bir rakama asla güvenmez. Teklif ile gönderim arasında fiyat ya da başlık kaydı değişirse kesilen tutar farklı olabilir. Kesin rakamı gönderim yanıtından okuyun.

Kesim atomiktir, iade tam olur

Cüzdan tek bir koşullu güncellemeyle kesilir: eşzamanlı iki gönderim bakiyeyi eksiye düşüremez. Sağlayıcı gönderimi reddederse kesilen tutar tamamen iade edilir ve hiçbir mesaj gitmez. Yani başarısız bir gönderim para kaybettirmez.

Alfabe dışına çıkmak parça sayısını artırır

Mesaj temel alfabede yazılmışsa bir parçaya daha çok karakter sığar; alfabe dışı tek bir harf bile metni diğer kodlamaya düşürür ve parça başına kapasite yarıdan aza iner. Tutar parça üzerinden hesaplandığı için maliyet birden büyür. Teklif ucundaki kodlama alanını okuyun.

Geçmiş numaraları taşımaz

Gönderim geçmişi özet satırlar verir; alıcı numaraları yalnız tek gönderimi okuduğunuzda gelir. Alıcı bazlı teslim raporu ise API'de hiç yoktur ve panelde kalır, çünkü sağlayıcıdan canlı çekilir.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası