🚀

المستقبل يبدأ من هنا: TurkeySMS API

مرحباً بك في المنصة المخصصة للمطورين. توفر واجهة برمجة التطبيقات (API) من TurkeySMS حلولاً برمجية متقدمة وآمنة لدمج خدمات الرسائل النصية القصيرة مباشرة في بنيتكم التحتية البرمجية، سواء كانت تطبيقات ويب، هواتف ذكية، أو أنظمة إدارة المؤسسات.

نحن نصمم أدواتنا لتعمل بسلاسة مع كافة البيئات البرمجية الحديثة مثل Node.js، Python، و C#، مع توفير دعم كامل ومكتبات برمجية (SDK) لتقليل وقت التطوير وضمان أعلى مستويات الأداء.

📖

متصفح API التفاعلي (Swagger)

اختبر قوة واجهة برمجة التطبيقات الخاصة بنا في الوقت الفعلي. تتيح لك وثائقنا التفاعلية تجربة النقاط الطرفية، وعرض المخططات، وفهم هياكل الاستجابة مباشرة من متصفحك.

TurkeySMS Swagger V4

متوافقة تماماً مع مواصفات OpenAPI 3.0. جرب إرسال SMS، OTP، والتقارير دون كتابة سطر كود واحد.

تشغيل الوثائق التفاعلية ←
Interactive API Documentation
🛡️

ارتقِ بتجربة عملائك

يمنحك الربط البرمجي مع TurkeySMS تحكماً كاملاً لإنشاء قنوات اتصال ذكية ومباشرة. من إرسال تنبيهات الأنظمة اللحظية إلى توثيق الهوية عبر OTP، نحن نوفر لك العمود الفقري لاتصالاتك البرمجية بأعلى معايير الأمان المتبعة دولياً.

💡
نحن لا نفرض أي رسوم على الربط البرمجي؛ هدفنا هو نجاح مشروعك. فريقنا متاح على مدار الساعة للإشراف الفني على عملية الربط مجاناً.

المتطلبات

لضمان تجربة ربط ناجحة وامتثالاً للقواعد التنظيمية، يرجى التأكد من استيفاء المتطلبات التالية:

🏢

تفعيل الحساب (E-imza)

يتطلب تفعيل الحساب في تركيا وجود توقيع إلكتروني (E-imza) معتمد لإتمام الإجراءات القانونية والموافقة على الخدمة.

💳

رصيد رسائل

يجب توفر رصيد (Credits) في حسابكم لتتمكن الواجهة البرمجية من معالجة طلبات الإرسال بنجاح.

🏷️

عنوان إرسال (Sender ID)

يجب الحصول على موافقة مسبقة لعنوان الإرسال (Title) ليظهر بجانب رسائلك لدى المستلمين.

🚀

بدء سريع

ابدؤوا بإرسال أول رسالة في 3 خطوات فقط:

⚡ أسرع طريقة للبدء

🔐

التحقق من الهوية

يتم التحقق من الهوية باستخدام مفتاح الـ API الفريد الخاص بك، والذي يتم إرساله ضمن جسم الطلب (JSON Body).

POSThttps://api.turkeysms.com.tr/sms/send

يمكنك الحصول على مفتاح الـ API من لوحة التحكم الخاصة بك في قسم حسابي ← إعدادات API.

⚠️
حافظ على سرية مفتاح الـ API الخاص بك. لا تقم أبداً بمشاركته في المستودعات العامة (مثل GitHub) أو في الأكواد التي تعمل في جهة العميل (Client-side).
🔍

فحص المصادقة والصلاحيات

واجهة احترافية تتيح لك التحقق من صحة مفتاح الـ API الخاص بك ومعرفة كافة الصلاحيات الممنوحة له (إرسال، OTP، رصيد) بالإضافة إلى حالة الحساب الحالية.

POSThttps://api.turkeysms.com.tr/auth/check

نموذج الطلب (CURL)

Bash — cURL
curl -X POST https://api.turkeysms.com.tr/auth/check \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY"
}'

نموذج الاستجابة (JSON)

JSON — 200 OK
{
    "result": true,
    "result_code": "TS-1000",
    "key_details": {
        "status": "Active",
        "permissions": {
            "post_request": true,
            "send_single_sms": true,
            "send_otp": true,
            "check_balance": true,
            "check_senderid": true,
            "manage_groups": true
        }
    },
    "account_summary": {
        "account_status": "Active",
        "balance": {
            "main": 1500,
            "international": 250
        }
    }
}

حمّلوا ملف TurkeySmsClient.php وضمّنوه في مشروعكم، ثم استخدموا الكود التالي:

PHP
require_once 'TurkeySmsClient.php';

$client = new TurkeySmsClient('YOUR_API_KEY');
$result = $client->sendSms('SenderID', '905xxxxxxxxx', 'مرحباً!');

if ($client->isLastSuccess()) {
    echo "✅ تم الإرسال! ID: " . $result['sms_id'];
}
✉️

إرسال رسالة فردية

لإرسال رسالة نصية واحدة لرقم محدد عبر طريقة POST:

POST https://api.turkeysms.com.tr/sms/send

المعاملات (Parameters)

المعامل النوع الحالة الوصف
api_key string مطلوب مفتاح API الخاص بحسابكم.
title string مطلوب عنوان الإرسال (Sender ID) كما هو مسجّل في حسابكم مع مراعاة حالة الأحرف.
text string مطلوب نص الرسالة المراد إرسالها. يدعم Unicode بالكامل.
sentto string مطلوب رقم المستقبل بالصيغة الدولية (مثال: 905xxxxxxxxx). أرقام فقط بدون رموز.
report int اختياري 1 لتفعيل تقرير العملية، 0 للإلغاء. الافتراضي: 1
sms_lang int اختياري لغة المحتوى: 0 إنجليزي، 1 تركي، 2 عربي/Unicode. الافتراضي: 2
content_type int اختياري 0 معاملات (Transactional)، 1 جودة عالية، 2 إعلاني. الافتراضي: 0
response_type string اختياري صيغة الاستجابة: json أو php. الافتراضي: json

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/sms/send \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "title": "CompanyName",
    "text": "مرحباً! هذه رسالة تجريبية.",
    "sentto": "905xxxxxxxxx",
    "sms_lang": 2,
    "content_type": 0
}'

مثال باستخدام PHP (cURL)

PHP — cURL
$data = [
    "api_key"       => "YOUR_API_KEY",
    "title"         => "CompanyName",
    "text"          => "مرحباً! هذه رسالة تجريبية.",
    "sentto"        => "905xxxxxxxxx",
    "report"        => 1,
    "sms_lang"      => 2,
    "content_type"  => 0,
    "response_type" => "json"
];

$ch = curl_init("https://api.turkeysms.com.tr/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

استجابة ناجحة

JSON — 200 OK
{
    "result":         true,
    "result_code":    "TS-1024",
    "result_message": "SMS dispatched successfully.",
    "sms_id":         1000007721,
    "number_of_sms":  1,
    "sms_lang":       "Arabic",
    "content_type":   "Transactional",
    "country":        "Turkey-TR"
}

شرح حقول الاستجابة

الحقلالوصف
resulttrue في حال النجاح، false في حال الفشل.
result_codeكود العملية (راجعوا جدول أكواد الاستجابة).
result_messageرسالة تشرح نتيجة العملية.
sms_idالمعرّف الفريد للرسالة — يمكن استخدامه لتتبع الحالة.
number_of_smsعدد الرسائل (الرصيد المخصوم).
sms_langلغة محتوى الرسالة المُرسلة.
content_typeنوع المحتوى (Transactional / High Quality / Advertising).
countryالدولة التي أُرسلت إليها الرسالة.
🔑

إرسال رمز تحقق (OTP)

الواجهة المخصصة لإرسال رموز التحقق من رقم الجوال (OTP). تتميز هذه الواجهة بالسرعة الفائقة وإعطائها الأولوية القصوى في تسليم الرسائل.

POST https://api.turkeysms.com.tr/otp/send

المعاملات (Parameters)

المعامل النوع الحالة الوصف
api_key string مطلوب مفتاح API الخاص بحسابكم.
mobile string مطلوب رقم المستقبل بالصيغة الدولية (مثال: 905xxxxxxxxx).
lang int اختياري لغة نص الرمز. 0 إنجليزي، 1 تركي، 2 عربي. الافتراضي: 2
digits int اختياري عدد خانات رمز OTP المراد توليده من النظام (4، 5 أو 6). الافتراضي: 4
report int اختياري 1 لطباعة التقرير، 0 للإلغاء. الافتراضي: 1
response_type string اختياري صيغة الاستجابة: json أو php. الافتراضي: json

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/otp/send \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "mobile": "905xxxxxxxxx",
    "lang": 2,
    "digits": 4
}'

مثال باستخدام PHP (cURL)

PHP — cURL
$data = [
    "api_key"       => "YOUR_API_KEY",
    "mobile"        => "905xxxxxxxxx",
    "lang"          => 2,
    "digits"        => 4,
    "report"        => 1,
    "response_type" => "json"
];

$ch = curl_init("https://api.turkeysms.com.tr/otp/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

استجابة ناجحة

JSON — 200 OK
{
    "result":         true,
    "sms_id":         654321,
    "otp_code":       1458,
    "number_of_sms":  1,
    "result_code":    "TS-1024",
    "result_message": "The message was sent successfully",
    "sms_lang":       "Arabic",
    "content_type":   "High_quality",
    "country":        "Turkey-TR"
}
🛡️

إرسال رمز OTP مخصص (Advanced OTP)

مسار متخصص لإرسال كلمات المرور لمرة واحدة (OTP) بنص مخصص من اختيارك.
هام جداً: يشترط وجود اسم مرسل (Sender ID) مفعل بحسابك لتتمكن من استخدام هذه الميزة، كما يجب إضافة المتغير TS-CODE داخل النص ليتم استبداله بالرمز برمجياً.

POSThttps://api.turkeysms.com.tr/otp/detailed

المعاملات (Parameters)

المعاملالنوعالحالةالوصف
api_keystringإلزاميمفتاح API الخاص بك.
mobilestringإلزاميرقم المستلم بالصيغة الدولية (مثال: 905xxxxxxxxx).
titlestringإلزامياسم المرسل (Sender ID) الخاص بك والمفعل بحسابك.
textstringإلزاميمحتوى الرسالة. ملاحظة: يجب وضع TS-CODE في مكان ظهور كود الـ OTP واستخدام TS-L للنزول لسطر جديد.
langintاختياريلغة النص: 0 إنكليزي، 1 تركي، 2 عربي. الافتراضي: 2
digitsintاختياريعدد خانات الكود المُولد (4، 5، أو 6). الافتراضي: 4
reportintاختياري1 لظهور تقرير الرد، 0 لإخفائه. الافتراضي: 1
response_typestringاختيارينوع الرد: json أو php. الافتراضي: json

نموذج الاستجابة (JSON)

JSON — 200 OK
{
    "result":         true,
    "sms_id":         654322,
    "otp_code":       8591,
    "number_of_sms":  1,
    "result_code":    "TS-1024",
    "result_message": "The message was sent successfully",
    "sms_lang":       "Arabic",
    "content_type":   "High_quality",
    "country":        "Turkey-TR"
}
📁

إدارة المجموعات

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

1. إنشاء مجموعة جديدة (Create)

POST https://api.turkeysms.com.tr/groups/create

المعاملات: api_key، group_name.

CURL
curl -X POST https://api.turkeysms.com.tr/groups/create \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "group_name": "My New Group"
}'

3. حذف مجموعة (Delete)

POST https://api.turkeysms.com.tr/groups/delete

المعاملات: api_key، group_id.

CURL
curl -X POST https://api.turkeysms.com.tr/groups/delete \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "group_id": 1234
}'

4. عرض قوائم المجموعات (List)

POST https://api.turkeysms.com.tr/groups/list

المعاملات: api_key، search (اختياري).

CURL
curl -X POST https://api.turkeysms.com.tr/groups/list \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "search": "Team"
}'

نموذج الاستجابة (قائمة المجموعات)

JSON
{
    "result": true,
    "result_code": "TS-1090",
    "groups_count": 2,
    "groups": [
        { "id": 123, "name": "Sales Team", "date": "2026-04-01" },
        { "id": 456, "name": "Vip Clients", "date": "2026-04-02" }
    ]
}
👤

إدارة جهات الاتصال (الأرقام)

تتيح لك كافه العمليات اللازمه لإضافة الأرقام إلى مجموعاتك الحالية أو حذفها، مع دعم الحقول المخصصة.

1. إضافة رقم إلى مجموعة (Add)

POST https://api.turkeysms.com.tr/contacts/add
CURL
curl -X POST https://api.turkeysms.com.tr/contacts/add \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "group_id": 1234,
    "gsm_number": "905051234567",
    "name": "Ahmet Yılmaz"
}'

نموذج الاستجابة (إضافة رقم)

JSON
{
    "result": true,
    "result_code": "TS-1100",
    "result_message": "Contact added successfully",
    "total_added": 1,
    "total_failed": 0,
    "mobile": "905050300074"
}

إرسال رسالة مجدولة

يمكنكم جدولة رسالة ليتم إرسالها في تاريخ ووقت محددين. يُستخدم نفس الرابط مع إضافة معاملات الجدولة.

POST https://api.turkeysms.com.tr/sms/send

معاملات الجدولة الإضافية

المعاملالنوعالحالةالوصف
scheduled_sms int مطلوب اضبطوه على 1 لتفعيل الجدولة.
scheduled_date string مطلوب تاريخ الإرسال بصيغة Y-m-d (مثال: 2026-12-31).
scheduled_time string مطلوب وقت الإرسال بنظام 24 ساعة بصيغة H:i (مثال: 13:10). التوقيت المحلي التركي Europe/Istanbul.

نموذج الطلب (CURL) - جدولة

CURL
curl -X POST https://api.turkeysms.com.tr/sms/send \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "title": "CompanyName",
    "text": "رسالة مجدولة",
    "sentto": "905xxxxxxxxx",
    "scheduled_sms": 1,
    "scheduled_date": "2026-12-31",
    "scheduled_time": "09:00"
}'

مثال باستخدام PHP (SDK)

PHP — SDK
$client = new TurkeySmsClient('YOUR_API_KEY');

$result = $client->sendScheduledSms(
    'CompanyName',       // عنوان الإرسال
    '905xxxxxxxxx',      // رقم المستقبل
    'ستصل هذه الرسالة في الموعد المحدد',
    '2026-12-31',         // التاريخ
    '09:00',              // الوقت
    2                     // عربي
);

استجابة ناجحة

JSON — 200 OK
{
    "result":         true,
    "result_code":    "TS-1024",
    "result_message": "SMS scheduled successfully.",
    "rapor_id":       987654,
    "scheduled_sms":  true,
    "scheduled_date": "2026-12-31",
    "scheduled_time": "09:00",
    "number_of_sms":  1,
    "sms_lang":       "Arabic",
    "country":        "Turkey-TR"
}
👥

الإرسال الجماعي

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

1. إرسال نص موحد لمجموعة أرقام

إرسال رسالة واحدة ثابتة لمجموعة من الأرقام (مصفوفة أرقام).

POST https://api.turkeysms.com.tr/group/send

2. إرسال نصوص متعددة لأرقام متعددة

إرسال نصوص مخصصة ومختلفة لمجموعة من الأرقام بحيث يتطابق ترتيب النص مع ترتيب الرقم في المصفوفة.

POST https://api.turkeysms.com.tr/group/sendMixed

نموذج الطلب (CURL) — نص موحد

CURL
curl -X POST https://api.turkeysms.com.tr/group/send \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "title": "SenderID",
    "text": "نص الرسالة الموحد للجميع",
    "sentto": ["905000000001", "905000000002"]
}'

نموذج الطلب (CURL) — نصوص متعددة

CURL
curl -X POST https://api.turkeysms.com.tr/group/sendMixed \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "title": "SenderID",
    "text": ["أهلاً أحمد", "أهلاً محمد"],
    "sentto": ["905000000001", "905000000002"]
}'

مثال على الطلب

PHP — SDK
$client = new TurkeySmsGroupClient('YOUR_API_KEY');

// إرسال نص موحد لعدة أرقام
$result = $client->sendSingleTextToMultipleNumbers(
    'SenderID',                     // عنوان المُرسل
    'نص الرسالة الموحد للجميع',         // النص
    ['905000000001', '905000000002']  // مصفوفة الأرقام
);

// إرسال نصوص متعددة مخصصة
$multiResult = $client->sendMultipleTextsToMultipleNumbers(
    'SenderID',
    ['أهلاً أحمد', 'أهلاً محمد'],
    ['905000000001', '905000000002']
);

مثال على استجابة الإرسال الجماعي

JSON — 200 OK
{
    "result":             true,
    "rapor_id":           123456,
    "total_mobile_num":   2,
    "number_of_sms":      2,
    "result_code":        "TS-1024",
    "result_message":     "The message was sent successfully",
    "sms_lang":           "Arabic",
    "country":            "Turkey-TR"
}
💰

الاستعلام عن الرصيد

يتيح لك هذا الـ Endpoint الاستعلام عن الرصيد المتاح حالياً في حسابك بشكل مباشر. يجب تفعيل خيار الاستعلام عن الرصيد في إعدادات مفتاح API الخاص بك من لوحة التحكم.

POST https://api.turkeysms.com.tr/balance/

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/balance/ \
-H "Content-Type: application/json" \
-d '{ "api_key": "YOUR_API_KEY" }'

مثال على استجابة الرصيد

JSON — 200 OK
{
    "result":                       true,
    "result_code":                  "TS-1040",
    "result_message":               "operation_success",
    "local_balance_sms":            5400,
    "international_balance_tl":     30.50
}

استخدام مكتبة SDK (PHP)

PHP
$client = new TurkeySmsBalanceClient('YOUR_API_KEY');
$result = $client->checkBalance();

if (!empty($result['result'])) {
    echo "رصيد الرسائل المحلية: " . $result['local_balance_sms'];
}
🏷️

الاستعلام عن عناوين الإرسال

تسمح هذه الواجهة بالاستعلام عن قائمة عناوين الإرسال (Sender IDs) المفعلة في حسابكم. يجب تفعيل خيار الاستعلام عن العناوين من إعدادات مفتاح الـ API في لوحة التحكم.

POST https://api.turkeysms.com.tr/senderid/check

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/senderid/check \
-H "Content-Type: application/json" \
-d '{ "api_key": "YOUR_API_KEY" }'

مثال باستخدام PHP (cURL)

PHP — cURL
$data = [
    "api_key" => "YOUR_API_KEY"
];

$ch = curl_init("https://api.turkeysms.com.tr/senderid/check");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

نموذج الاستجابة الناجحة

JSON — 200 OK
{
    "result": true,
    "result_code": "TS-1040",
    "result_message": "Operation success",
    "sender_ids": [
        {
            "id": 12345,
            "title": "TurkeySMS",
            "status": 1,
            "document": 1,
            "network_stat": 1
        }
    ]
}
📊

تقارير الإرسال

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

1. التقرير الأساسي (Summary)

يعرض إحصائيات عامة عن الإرسالية مثل عدد الرسائل الناجحة، الفاشلة، والمرفوضة.

POST https://api.turkeysms.com.tr/reports/basic

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/reports/basic \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "raporid": 12345
}'

نموذج الاستجابة (تقرير أساسي)

JSON
{
    "result":   true,
    "rapor_id": 12345,
    "total_numbers": 1000,
    "success_count": 950,
    "failed_count":  30,
    "pending_count": 20
}

مثال باستخدام PHP (cURL)

PHP — cURL
$data = [
    "api_key" => "YOUR_API_KEY",
    "raporid" => 12345
];

$ch = curl_init("https://api.turkeysms.com.tr/reports/basic");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

2. التقرير التفصيلي (Detailed)

يعرض حالة كل رقم هاتف على حدة. يدعم هذا التقرير نظام الترقيم (Pagination) حيث يتم عرض 500 رقم في كل صفحة.

POST https://api.turkeysms.com.tr/reports/detailed

نموذج الطلب (CURL) — التقرير التفصيلي

PHP — cURL
$data = [
    "api_key" => "YOUR_API_KEY",
    "raporid" => 12345,
    "page"    => 1
];

$ch = curl_init("https://api.turkeysms.com.tr/reports/detailed");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

البارامترات المدعومة

المعاملالنوعالوصف
api_keyStringمفتاح الـ API الخاص بك. مطلوب
raporidIntegerرقم التقرير (ID) الذي حصلت عليه بعد عملية الإرسال. مطلوب
pageIntegerرقم الصفحة المطلوبة (للتقرير التفصيلي فقط). الافتراضي هو 1.

نموذج الاستجابة (تقرير تفصيلي)

JSON
{
    "result": true,
    "result_code": "TS-1064",
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "total_records": 2350
    },
    "data": [
        {
            "phone_number": "905xxxxxxxxx",
            "sent_at": "2026-04-03 12:00:00",
            "sms_status": "Number received the message"
        }
    ]
}
🚫

إدارة القائمة السوداء

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

1. إضافة رقم للحظر (Add to Blacklist)

POST https://api.turkeysms.com.tr/blacklist/add

البارامترات المطلوبة: api_key, number.

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/blacklist/add \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "number": "905xxxxxxxx"
}'

نموذج الاستجابة (إضافة)

JSON
{
    "status": "success",
    "result_code": "TS-1141",
    "result_message": "Number added to blacklist successfully"
}

2. الاستعلام عن حالة الحظر (Check Status)

POST https://api.turkeysms.com.tr/blacklist/status

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/blacklist/status \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "number": "905xxxxxxxx"
}'
JSON Response (Blocked)
{
    "status": "success",
    "result_code": "TS-1143",
    "is_blocked": true,
    "block_date": "2026-04-03",
    "block_time": "17:50"
}
📄

حالة الرسالة (SMS Status)

تسمح هذه الواجهة بالاستعلام عن حالة تسليم رسالة معينة باستخدام المعرف الفريد (SMS ID) الذي تم استلامه عند الإرسال.

POST https://api.turkeysms.com.tr/sms/status

البارامترات المطلوبة

البارامترالنوعالوصف
api_keyStringمفتاح الـ API الخاص بك. مطلوب
sms_idIntegerالمعرف الفريد للرسالة المستلم من ناجيا الإرسال. مطلوب

نموذج الطلب (CURL)

CURL
curl -X POST https://api.turkeysms.com.tr/sms/status \
-H "Content-Type: application/json" \
-d '{
    "api_key": "YOUR_API_KEY",
    "sms_id": 12345678
}'
JSON
{
    "status": "success",
    "result_code": "TS-1064",
    "result_message": "Number received the message.",
    "result": true,
    "sender_id": "SENDER",
    "sms_status": "Number received the message",
    "sms_balance": "1 SMS"
}
⚙️

خيارات الإرسال

لغة محتوى الرسالة — sms_lang

القيمةاللغةالوصف
0Englishالرسالة بالإنجليزية (GSM 7-bit encoding)
1Türkçeالرسالة بالتركية مع دعم الأحرف التركية الخاصة
2العربية / Unicodeالرسالة بالعربية أو أي لغة تستخدم UTF-8

نوع المحتوى — content_type

القيمةالنوعالوصف
0Transactionalرسالة متعلقة بعملية أو تفاعل مع المستخدم (OTP، تأكيد طلب ...)
1High Qualityرسالة بجودة عالية — تسويقية أو إعلامية
2Advertisingرسالة إعلانية ترويجية

صيغة الاستجابة — response_type

القيمةالصيغة
jsonالاستجابة بصيغة JSON (الافتراضي)
phpالاستجابة بصيغة PHP Array
📊

أكواد الاستجابة

كل عملية تُرجع كود حالة يوضح نتيجتها. استخدموا هذا الجدول لتشخيص أي مشكلة.

الكودHTTPالوصف
TS-1072400تكرار في أرقام الوجهة.
TS-1140400الرقم محجوب مسبقاً لهذا المستخدم.
TS-1141200تم إضافة الرقم للقائمة السوداء بنجاح.
TS-1142200الرقم غير موجود في القائمة السوداء.
TS-1143200الرقم محجوب حالياً.
TS-1144400تنسيق رقم الهاتف غير صحيح.
TS-1080200تم إنشاء المجموعة بنجاح.
TS-1081403صلاحية إنشاء المجموعات غير مفعلة.
TS-1082400اسم المجموعة موجود مسبقاً.
TS-1083400اسم المجموعة غير صالح.
TS-1084403صلاحية تعديل المجموعات غير مفعلة.
TS-1085403صلاحية حذف المجموعات غير مفعلة.
TS-1086404المجموعة غير موجودة أو غير مصرح بالوصول إليها.
TS-1087200تم تعديل المجموعة بنجاح.
TS-1088200تم حذف المجموعة بنجاح.
TS-1089403صلاحية عرض المجموعات غير مفعلة.
TS-1090200تم جلب قائمة المجموعات بنجاح.
TS-1024200تم الإرسال بنجاح.
TS-1040200تم الاستعلام عن الرصيد بنجاح.
TS-1025400رقم المستقبل مفقود أو غير صحيح.
TS-1026400نص الرسالة مفقود أو فارغ.
TS-1027403الرصيد غير كافٍ لإتمام عملية الإرسال.
TS-1028403عنوان الإرسال (Sender ID) غير مفعّل أو غير موثق.
TS-1036403خيار إرسال الـ OTP العادي غير مفعّل لهذا المفتاح.
TS-1037403خيار إرسال الـ OTP المتقدم غير مفعّل لهذا المفتاح.
TS-1060403تم تجاوز حد الإرسال المسموح في الدقيقة الواحدة.
TS-1030403الحساب غير مفعّل أو موقوف مؤقتاً.
TS-1031401مفتاح API غير صالح أو غير مفعّل.
TS-1032403خدمة الإرسال الدولي غير مفعّلة لهذا الحساب.
TS-1033400صيغة البيانات المُرسلة غير صالحة (ليست JSON).
TS-1034400عنوان الإرسال (title) مفقود أو يحتوي على رموز غير مسموحة.
TS-1050401مفتاح API مفقود من الطلب.
TS-1061403صلاحية الإرسال عبر POST غير مفعّلة لهذا المفتاح.
TS-1065403صلاحيات المفتاح لا تسمح بالقيام بهذه العملية (الخدمة معطلة للحساب).
TS-1066403صلاحية الإرسال الجماعي (Group Send) غير مفعّلة لهذا المفتاح.
TS-1072400هناك أرقام مكررة في مصفوفة الإرسال الجماعي.
TS-1063403صلاحية الاستعلام عن الحالة غير مفعلة.
TS-1052400المعرف الفريد للرسالة (sms_id) مفقود.
TS-1064200تم استلام الرسالة بنجاح.
TS-1023200الرقم خارج التغطية، لم يتم استلام الرسالة بعد.
TS-1100200تم إضافة الرقم لجهة الاتصال بنجاح.
TS-1101400فشل إضافة الرقم لجهة الاتصال أو الرقم موجود مسبقاً.
TS-1022200الرقم لم يستلم الرسالة (فشل التسليم).
📦

المكتبات البرمجية (SDK)

لبدء الدمج بسرعة قصوى، وفرنا لكم مكتبات برمجية جاهزة (SDK) ومعالجة بالكامل لأشهر لغات البرمجة. تدعم جميع المكتبات ميزات الإرسال الفوري، OTP، الإرسال المجدول، والإرسال الجماعي.

تتوفر الآن وثائق Swagger التفاعلية لتجربة الأكواد مباشرة من المتصفح.
🔗

Webhooks (تقارير الإرسال اللحظية)

بدلاً من الاستعلام المتكرر عن حالة الرسائل، يوفر نظام TurkeySMS ميزة الـ Webhooks التي تقوم بدفع تقارير الإرسال المفصلة (Detailed Reports) إلى سيرفرك فور تحديثها لدى المشغل. هذا يقلل من استهلاك موارد سيرفرك ويضمن تحديث البيانات لحظياً.

🛠️
يمكنك تفعيل هذه الميزة وإضافة رابط الاستقبال (Webhook URL) من داخل لوحة التحكم في قسم إعدادات الـ API.

تأمين الاستقبال (Signature Verification)

لضمان أن البيانات قادمة من سيرفراتنا فعلاً، نرسل في الترويسة (Header) القيمة التالية: X-TurkeySms-Signature. وهي عبارة عن تشفير لمحتوى البيانات باستخدام Secret Key الخاص بك (HMAC-SHA256).

نموذج كود استقبال (PHP)

PHP
<?php
$secret = "YOUR_WEBHOOK_SECRET";
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TURKEYSMS_SIGNATURE'] ?? '';

// التحقق من التوقيع للأمان
$expectedSignature = hash_hmac('sha256', $payload, $secret;

if (hash_equals($expectedSignature, $signature {
    $data = json_decode($payload, true;
    // معالجة تقرير الرسالة هنا
    file_put_contents('sms_log.txt', $data['data']['sms_id'] . ": " . $data['data']['status'];
    http_response_code(200;
} else {
    http_response_code(403; // رفض الطلب غير الموثق
}
?>
🌀

التكامل مع منصة Make.com

قم بدمج TurkeySMS بشكل أصلي في سيناريوهات Make.com (Integromat سابقاً). ومن خلال تطبيقنا الرسمي، يمكنك أتمتة تدفقات عمل الاتصالات الخاصة بك دون كتابة سطر واحد من الكود.

🔗
يمكنك إضافة تطبيق TurkeySMS إلى حسابك في Make باستخدام رابط التكامل الرسمي.

الموديولات المتاحة

كيفية الإعداد

  1. في سيناريو Make.com الخاص بك، قم بإضافة موديول TurkeySMS.
  2. انقر فوق Add Connection وقم بتسميته (على سبيل المثال، "حسابي").
  3. قم بلصق API Key الخاص بك من لوحة تحكم TurkeySMS.
  4. قم بتكوين معلمات الموديول الخاص بك وابدأ الأتمتة!
🧩

التكامل (Integrations)

نحن نوفر حلولاً جاهزة للدمج مع أشهر المنصات العالمية لتسهيل تجربة الاستخدام دون الحاجة لكتابة كود برمجي معقد.

💡
تدعم حلولنا البرمجية تنبيهات WooCommerce، وميزة الـ auto-discovery في Laravel والقوالب الذكية لتسهيل عملك.

مستعرض الكود