API ile SMS Gönderme: Python, Node.js, PHP ve cURL Örnekleri

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "447700900123",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

// Node.js 18+ (yerleşik fetch)
const res = await fetch("https://api.broadnet.me/sms/sendSms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "OmniDemo",
    destinationNumber: "447700900123",
    message: "Your OmniDemo code is 482913",
    messageType: "TEXT",
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const messageId = await res.text(); // düz metin mesaj kimliği

import os
import requests

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "447700900123",
        "message": "Your OmniDemo code is 482913",
        "messageType": "TEXT",
    },
    timeout=15,
)
r.raise_for_status()
message_id = r.text  # düz metin mesaj kimliği, JSON değil

<?php
$payload = json_encode([
    "senderId" => "OmniDemo",
    "destinationNumber" => "447700900123",
    "message" => "Your OmniDemo code is 482913",
    "messageType" => "TEXT",
]);

$ch = curl_init("https://api.broadnet.me/sms/sendSms");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BROADNET_TOKEN"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$messageId = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status . " " . $messageId . PHP_EOL;

2603121407537573731

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "971500000000",
        "message": "رمز التحقق الخاص بك هو 482913",
        "messageType": "UNICODE",
        "campaignName": "login-otp",
    },
    timeout=15,
)

Göndermeden önce segmentleri nasıl sayarım?

Mesajla POST /sms/identify çağırın. Tespit edilen kodlamayı, karakter sayısını, segment sayısını ve segment başına sınırı döndürür.

curl -X POST https://api.broadnet.me/sms/identify \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your OmniDemo code is 482913" }'

{
  "message": "Your OmniDemo code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 28,
  "charLimit": 160
}

smsParts (smscount'tan), charCount ve charLimit değerlerini bir gönderim isteğine aktarabilirsiniz. GSM-7 metin yanıtta GSM-7 olarak etiketlenebilir; bunu TEXT olarak gönderin.

Çok sayıda numaraya nasıl gönderirim?

Bir alıcı dosyası ve ayarların JSON dizesiyle multipart/form-data bir istek olan POST /sms/sendbulk kullanın.

curl -X POST https://api.broadnet.me/sms/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F destinationNumberFile=@recipients.csv \
  -F 'bulkRequest={"senderId":"OmniDemo","message":"Your statement is ready in the app.","messageType":"TEXT","campaignName":"oct-statements","allowDuplicate":false}'

import json
import os
import requests

bulk_request = {
    "senderId": "OmniDemo",
    "message": "Your statement is ready in the app.",
    "messageType": "TEXT",
    "campaignName": "oct-statements",
    "allowDuplicate": False,
}

with open("recipients.csv", "rb") as f:
    r = requests.post(
        "https://api.broadnet.me/sms/sendbulk",
        headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
        files={"destinationNumberFile": ("recipients.csv", f, "text/csv")},
        data={"bulkRequest": json.dumps(bulk_request)},
        timeout=60,
    )
print(r.json())

Yanıt, bulkSessionId ile total, validCount, invalidCount ve duplicate içeren bir bulkListInfo nesnesi içerir. bulkSessionId değerini kampanyayla birlikte saklayın. İşler referanstaki uç noktalarla listelenebilir, duraklatılabilir, sürdürülebilir ve iptal edilebilir. Büyük bir gönderimden önce numaraları POST /sms/lookup ile de kontrol edebilirsiniz; HLR sorgusu rehberimize bakın.

İletim durumunu nasıl alırım?

İletim durumları hesabınızda yapılandırılan webhook URL'sine itilir. Bir mesaj SUBMITTED ve SENT aşamalarından DELIVERED durumuna ilerler ya da FAILED veya REJECTED olarak sonlanır. Ekibimize herkese açık HTTPS URL'sini verirsiniz; bayiler alt hesap başına bir webhook alabilir.

Yük alanları kanala göre değişir ve API belirtimi tek bir webhook şeması tanımlamaz; bu yüzden önce ham gövdeyi günlüğe alın ve alanları hesabınızdaki gerçek bir olaydan eşleyin. Asgari bir alıcı olayı saklar ve hızla onaylar:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // kendi depolamanız; asenkron işleyin
  res.sendStatus(200);             // hızla onaylayın
});

app.listen(3000);

İşlemeyi idempotent yapın; çünkü aynı durum iki kez gelebilir ve geç gelen bir SENT saklanmış bir DELIVERED'ın üzerine asla yazmamalıdır. Uç noktanız çalışmıyorsa POST /sms/resendDlr bir tarih aralığı için raporları yeniden iter:

curl -X POST https://api.broadnet.me/sms/resendDlr \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-10-09",
    "endDate": "2026-10-10",
    "senderId": "OmniDemo",
    "messageStatus": "DELIVERED"
  }'

Webhook rehberinde ve mesaj iletim durumları açıklaması yazısında daha fazlasını okuyun.

Hataları nasıl yönetir ve mükerrer gönderimden nasıl kaçınırım?

Önce HTTP durumunu, sonra hata gövdesini ele alın. Yalnızca ağ hatalarını, 429 ve 5xx durumlarını yeniden deneyin.

API'nin döndürdüğü hatalar status, error, message, errorCode ve requestUri alanlı beş alanlı bir JSON gövdesi kullanır. Belgelenmiş varsayılan REST limiti sürekli saniyede 200 istektir; hesabınızın limitleri kimlik bilgilerinizle birlikte teyit edilir.

API idempotency anahtarı kabul etmez. Bir istek başarılı olurken yanıtı kaybolabilir ve kör bir yeniden deneme iki kez gönderir. Çağırmadan önce kendi işlem kimliğinizle anahtarlanmış bir bekleyen satır yazın, dönen mesaj kimliğini saklayın ve zaman aşımından sonra yeniden göndermeden önce bir webhook durumu olup olmadığına bakın. Toplu gönderimlerde allowDuplicate değerini false yapın. Ayrıntılar Hatalar ve limitler sayfasında.

Örnek senaryo: Bölgesel bir uygulama için giriş kodları

BAE'li bir perakendeci olan "Souq Rafiq" (kurgusal) giriş kodlarını SMS ile gönderir.

1. Kimlik doğrulama servisi altı haneli bir kod üretir, beş dakikalık geçerlilikle bir hash saklar ve pending bir gönderim satırı yazar.
2. Arapça kullanıcılar için messageType=UNICODE, İngilizce kullanıcılar için TEXT ile /sms/sendSms çağırır.
3. 200 alınca mesaj kimliğini saklar.
4. Webhook işleyicisi satırı DELIVERED, FAILED veya REJECTED olarak işaretler.
5. Kısa bir beklemeden sonra durum DELIVERED değilse uygulama yeniden gönderme ve yapılandırılmışsa başka bir kanal sunar. Kanal fallback'ine bakın.
6. Numara ve IP başına kod isteği sınırları kötüye kullanıma karşı korur; bkz. SMS pumping önleme.

Yaygın hatalar nelerdir?

• Gönderim yanıtında r.json() çağırmak. Yanıt düz metindir.
• Yanlış alan adları. senderId, destinationNumber ve message kullanın; to, from veya text gibi alanlar bu uç noktanın parçası değildir.
• Numaralarda artı işareti ve baştaki sıfır.
• Arapça için UNICODE'u unutmak; bu, metni bozar.
• Kayıtsız gönderici kimlikleri. Bazı ülkeler bunları engeller veya değiştirir; hedef ülkeniz için gönderici kimliği kurallarını kontrol edin ve kaydı bizden isteyin.
• 200'ü iletildi saymak.
• Token'ın bir mobil uygulamada veya tarayıcıda olması; orada herkes onu çıkarabilir.
• Limitler: bu rehber yaygın isteği gösterir. Zamanlama biçimleri gibi isteğe bağlı alanlar ekibimizle teyit edilmelidir.

OmniChannels.ai nasıl yardımcı olur?

OmniChannels.ai, A2P SMS'i BroadNet'in doğrudan operatör bağlantısı üzerinden; iki yönlü SMS, gönderici kimlikleri, Unicode ve Arapça, HLR sorgusu ve yüksek hacim için SMPP 3.4 ile gönderir. https://api.broadnet.me adresindeki REST API Bearer token kullanır, ayrıca WhatsApp, RCS ve diğer kanalları kapsar; iletim durumları tek bir webhook biçiminde normalleştirilir. Ekibimiz gönderici kimliği kayıtlarını sizinle birlikte hazırlar. SMS API referansına veya SMS kanalına bakın.