BroadNet
المجلةهندسة
هندسة

كيفية إرسال SMS عبر الكود: Python، PHP، Node.js، Java، Go و C# باستخدام استدعاء REST واحد

يعد إرسال SMS عبر الكود عبارة عن طلب HTTPS POST موثق واحد: يتضمن رمز Bearer، وجسم طلب JSON يحتوي على معرّف المُرسِل، ورقم الوجهة، والرسالة، ونوع الرسالة، بالإضافة إلى معرف الرسالة في الرد. إليك نفس الطلب بلغات Python، PHP، Node.js، Java، Go و C#، بالإضافة إلى معالجة الأخطاء ونصائح للإنتاج.

9 دقائق قراءة
هندسة · العدد 28
9 دقائق قراءة

إرسال SMS من الكود، قم بإجراء طلب HTTPS POST إلى https://api.broadnet.me/sms/sendSms مع ترويسة Authorization: Bearer وجسم طلب JSON يحتوي على senderId و destinationNumber والرسالة و messageType. ستُعيد العملية الناجحة الرمز HTTP 200 مع معرف الرسالة في جسم الاستجابة؛ بينما سيصل إشعار نتيجة التسليم لاحقاً كإيصال تسليم (DLR) إلى خطاف الويب (webhook) الخاص بك. تستخدم كل لغة أدناه مكتبة HTTP القياسية الخاصة بها فقط؛ أما الـ SDK الرسمي الوحيد فهو مخصص لـ TypeScript و Node.js.

النقاط الرئيسية

  • نقطة النهاية (Endpoint): طلب POST إلى https://api.broadnet.me/sms/sendSms, مع جسم طلب JSON ورمز Bearer.
  • الحقول المطلوبة: senderId، destinationNumber (بالتنسيق الدولي بدون علامة الزائد)، والرسالة، و messageType (TEXT).
  • الرد: 200 مع معرف الرسالة؛ احتفظ به لمطابقته مع إيصالات التسليم (DLR).
  • الأخطاء: الرمز المفقود أو غير الصالح يؤدي إلى استلام خطأ 401 من البوابة؛ أما أخطاء API فتعيد الحالة (status)، والخطأ (error)، والرسالة (message)، ورمز الخطأ (errorCode)، ومعرف طلب الـ (requestUri).
  • الـ SDK الرسمي الوحيد: @broadnet/cpaas-sdk لـ TypeScript/Node.js؛ يمكنك إنشاء عملاء (clients) للغات الأخرى من مواصفات OpenAPI.

ما الذي تحتاجه قبل البدء بالإرسال؟

  • رمز وصول (access token) من حساب BroadNet الخاص بك، ويُحفظ في متغير بيئة (BROADNET_TOKEN أدناه)، ولا يُوضع أبداً في الكود المصدري أو في تطبيق الهاتف المحمول.
  • معرّف مُرسِل مسموح به في الدولة الوجهة؛ تتطلب بعض الدول التسجيل أولاً.
  • رقم الوجهة بالتنسيق الدولي، على سبيل المثال 447700900123 (رقم وهمي من المملكة المتحدة).

يتم توفير الوصول التجريبي من قِبل مهندسينا: اطلب الوصول وستحصل على بيانات اعتماد تجريبية خلال يوم عمل واحد، وعادةً ما يتم إرسال أول رسالة تجريبية بعد خمس دقائق تقريباً من ذلك. يوضح دليل البدء السريع كيفية القيام بذلك.

كيف يبدو شكل الطلب؟

إليك الطلب مع cURL. كل مثال أدناه يرسل نفس محتوى JSON.

snippet
curl -X POST https://api.broadnet.me/sms/sendSms \
-H "Authorization: Bearer $BROADNET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}'
# 200 OK → response body is the message ID, e.g. 2603121407537573731

كيف ترسل SMS مع Python؟

باستخدام مكتبة requests، تقوم الوسيطة (argument) json= بضبط ترويسة Content-Type نيابة عنك.

snippet
import os, requests
r = requests.post(
"https://api.broadnet.me/sms/sendSms",
headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
json={
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT",
},
)
print(r.status_code, r.text) # message ID

كيف ترسل SMS مع PHP؟

إضافة curl الخاصة بـ PHP كافية؛ لا حاجة لاستخدام أي حزمة أخرى.

snippet
<?php
$ch = curl_init("https://api.broadnet.me/sms/sendSms");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BROADNET_TOKEN"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"senderId" => "BroadNet",
"destinationNumber" => "447700900123",
"message" => "Your verification code is 482913",
"messageType" => "TEXT",
]),
]);
$messageId = curl_exec($ch);
echo $messageId;

كيف ترسل SMS باستخدام Node.js؟

تتضمن الإصدارات Node.js 18 وما بعدها خاصية fetch مدمجة:

snippet
// Node.js 18+ (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: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
}),
});
console.log(await res.text()); // message ID

أو استخدم SDK TypeScript/Node.js الرسمي، @broadnet/cpaas-sdk:

snippet
// npm install @broadnet/cpaas-sdk axios
import { Configuration, SMSSMSApi } from "@broadnet/cpaas-sdk";
const sms = new SMSSMSApi(
new Configuration({
basePath: "https://api.broadnet.me",
accessToken: process.env.BROADNET_TOKEN!,
}),
);
const res = await sms.smsSendsmsPost({
sMSSmsRequest: {
senderId: "BroadNet",
destinationNumber: "447700900123",
message: "Your verification code is 482913",
messageType: "TEXT",
},
});
console.log(res.data); // message ID

كيف ترسل SMS باستخدام Java؟

تتضمن الإصدارات Java 11 وما بعدها java.net.http.HttpClient:

snippet
// Java 11+ — java.net.http is built in, nothing to install
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendSms {
public static void main(String[] args) throws Exception {
String json = "{"
+ "\"senderId\": \"BroadNet\", "
+ "\"destinationNumber\": \"447700900123\", "
+ "\"message\": \"Your verification code is 482913\", "
+ "\"messageType\": \"TEXT\""
+ "}";
HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.broadnet.me/sms/sendSms"))
.header("Authorization", "Bearer " + System.getenv("BROADNET_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.statusCode() + " " + res.body()); // 200 + message ID
}
}

كيف ترسل SMS باستخدام Go؟

snippet
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body := []byte(`{
"senderId": "BroadNet",
"destinationNumber": "447700900123",
"message": "Your verification code is 482913",
"messageType": "TEXT"
}`)
req, err := http.NewRequest(http.MethodPost, "https://api.broadnet.me/sms/sendSms", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BROADNET_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
id, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(id)) // 200 + message ID
}

كيف ترسل SMS باستخدام C# و .NET؟

لا تتطلب الإصدارات .NET 6 وما بعدها حزمة NuGet: HttpClient و System.Net.Http.Json مدمجان.

snippet
// .NET 6+ console app (Program.cs) — HttpClient is built in, no NuGet package
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("BROADNET_TOKEN"));
// PostAsJsonAsync sends Content-Type: application/json
var res = await http.PostAsJsonAsync("https://api.broadnet.me/sms/sendSms", new
{
senderId = "BroadNet",
destinationNumber = "447700900123",
message = "Your verification code is 482913",
messageType = "TEXT",
});
var id = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode} {id}"); // 200 + message ID

ما هي الاستجابة، وكيف تتعامل مع الأخطاء؟

الاستجابةالمعنىالإجراء المطلوب
200 + معرف الرسالةتم القبول للتسليماحفظ المعرف مع سجلاتك الخاصة؛ وانتظر DLR
400خطأ في التحقق أو حقل مفقودقم بتصحيح الطلب؛ لا تحاول الإرسال مجدداً دون تغيير
401رمز Bearer مفقود أو غير صالحتحقق من الرمز (token) وترويسة التفويض (Authorization header)
500خطأ غير متوقع في الخادمأعد المحاولة مع استخدام خاصية التراجع التدريجي (backoff)؛ تحقق من حالة الرسالة قبل إعادة إرسالها

تعني الرمز 200 أن المنصة قد قبلت الرسالة، وليس أن الهاتف قد استلمها. يتم الإبلاغ عن التسليم عبر إيصال التسليم (DLR)؛ راجع ما هو DLR و إيصالات التسليم (DLR) وأكواد الخطأ SMS. لا يحتوي API على ترويسة تكرار العمليات (idempotency header)، لذا يرجى الاحتفاظ بمعرّف الرسالة المُعاد والتحقق من حالتها قبل إعادة الإرسال لتجنب تكرار الرسائل. تسرد صفحة أكواد الخطأ بقية الأكواد.

كيف تجعل النظام جاهزاً للتشغيل الفعلي (production-ready)؟

  • احتفظ بالرمز (token) في جانب الخادم (server-side). لا تقم أبداً باستدعاء API SMS من متصفح أو تطبيق هاتف محمول حيث يمكن استخراج الرمز؛ بدلاً من ذلك، استدعِ الواجهة الخلفية (backend) الخاصة بك.
  • أرسل الرسائل الطويلة عن علم: يتسع GSM-7 لـ 160 حرفاً لكل SMS، بينما يتسع Unicode (UCS-2) لـ 70 حرفاً، ويتم تقسيم النصوص الأطول إلى أجزاء يتم احتساب تكلفتها. اطلع على حد الـ SMS لعدد الأحرف.
  • قم بجدولة عمليات الإرسال الجماعي واحترم معدل نقل الرسائل (TPS) الخاص بحسابك؛ اقرأ حدود المعدل.
  • استلم إيصالات التسليم (DLR) عبر خطاف الويب (webhook) وقم بتخزين الحالة النهائية.
  • قم أولاً بالتحقق من صحة الأرقام وتحويلها إلى الصيغة الدولية؛ راجع التحقق من صحة رقم الهاتف E.164.

بالنسبة للأحجام الكبيرة جداً أو لمجموعات تقنيات الاتصالات الحالية، قد يكون SMPP أنسب من REST؛ راجع SMPP مقابل REST. تدعم منصة BroadNet معالجة 30,000 SMS في الثانية لكل عقدة.

الأسئلة الشائعة

ما هي أبسط طريقة لإرسال SMS من خلال الكود؟

إجراء طلب HTTPS POST واحد إلى SMS API باستخدام رمز وصول (access token) وجسم طلب (body) من نوع JSON. مع BroadNet، يكون الطلب عبارة عن POST https://api.broadnet.me/sms/sendSms مع senderId، وdestinationNumber، والرسالة وmessageType.

هل يوجد BroadNet SDK لـ Python، أو PHP، أو Java؟

لا. يوجد SDK @broadnet/cpaas-sdk رسمي واحد لـ TypeScript وNode.js. تستدعي اللغات الأخرى الـ REST API مباشرة، كما هو موضح هنا، أو تقوم بإنشاء عميل (client) من مواصفات OpenAPI.

ما هي الصيغة التي يجب أن يكون عليها رقم الهاتف؟

الصيغة الدولية مع رمز الدولة وبدون علامة زائد (+) أو مسافات، على سبيل المثال 447700900123.

هل تعني استجابة 200 أنه تم تسليم الـ SMS؟

لا، بل يعني ذلك أنه تم قبول الرسالة. أما إيصال التسليم (DLR) فيوضح ما إذا كانت الرسالة قد وصلت إلى الهاتف المحمول.

هل يمكنني إرسال SMS مباشرة من تطبيق Android أو iOS؟

ليس بشكل آمن. يجب وضع استدعاء API على خادمك الخاص بحيث لا يتم إرسال رمز الوصول داخل التطبيق أبداً، واجعل التطبيق يقوم باستدعاء خادمك.

أين يمكنني العثور على مرجع API الكامل؟

في مرجع API ومواصفات OpenAPI.

نماذج الأكواد هي تلك الموجودة في صفحات المطورين الخاصة بنا، والتي تم التحقق منها وفقاً لمواصفات OpenAPI المنشورة. تمت المراجعة في 28 سبتمبر 2026. راجع معايير التحرير الخاصة بنا.

هل كان هذا مفيداً؟

كيف نكتب المحتوى ونراجعه

بقلم

فريق التحرير في BroadNet

ينشر فريق التحرير مدونة BroadNet. تُكتب المقالات مع فرق BroadNet للشؤون التنظيمية والمنتجات والهندسة وأبحاث الصناعة وحلول المشغّلين، وتُراجَع وفق معاييرنا التحريرية.

تابع القراءة

ثلاثة أخرى من المجلة.

اطلع على جميع المقالات
المجلة، عبر البريد الإلكتروني

مقال واحد شهرياً. لا شيء آخر.

اشترك وسنرسل لك المقال التالي - سواءً كان هندسيًا أو تنظيميًا أو صناعيًا - في يوم شحنه. لا حملات تسويقية عشوائية، ولا عروض منتجات، ولا مشاركة مع جهات خارجية. يمكنك إلغاء الاشتراك بنقرة واحدة.

نرسل رسالة واحدة شهريًا. يمكنك إلغاء الاشتراك في أي وقت. اطّلع على سياسة الخصوصية.

ما ستحصل عليه
  • مقال مطوّل، وليس مجرد رابط لجذب الانتباه.
    من ست إلى إحدى عشرة دقيقة من الكتابة المركزة حول موضوع واحد.
  • كتبه مشغّلون
    مهندسون، ومسؤولون عن الشؤون التنظيمية، وكتابة المنتجات داخل الشركة.
  • مدرك للمنطقة
    نظرة متعمقة من منطقة الشرق الأوسط وشمال أفريقيا حول الجهات التنظيمية والمشغّلين ومزيج القنوات.
  • مرة واحدة في الشهر
    لا حملة ترويجية بالتنقيط. مقال واحد فقط عندما يكون هناك مقال واحد للمشاركة.
توقف عن القراءة. ابدأ الشحن.

معظم ما نكتبه تعلمناه أثناء الإنتاج.

إذا لاقت هذه المعلومات استحسانك، فلنتحدث. أخبرنا عن حالة الاستخدام، والأحجام، والأسواق - وسنعود إليك بمعلومات عن التوجيه والتسعير، وعميل مرجعي يمكنك الاتصال به.

$ curl -X POST https://api.broadnet.me/sms/sendSms