المستقبل يبدأ من هنا: TurkeySMS API
مرحباً بك في المنصة المخصصة للمطورين. توفر واجهة برمجة التطبيقات (API) من TurkeySMS حلولاً برمجية متقدمة وآمنة لدمج خدمات الرسائل النصية القصيرة مباشرة في بنيتكم التحتية البرمجية، سواء كانت تطبيقات ويب، هواتف ذكية، أو أنظمة إدارة المؤسسات.
نحن نصمم أدواتنا لتعمل بسلاسة مع كافة البيئات البرمجية الحديثة مثل Node.js، Python، و C#، مع توفير دعم كامل ومكتبات برمجية (SDK) لتقليل وقت التطوير وضمان أعلى مستويات الأداء.
متصفح API التفاعلي (Swagger)
اختبر قوة واجهة برمجة التطبيقات الخاصة بنا في الوقت الفعلي. تتيح لك وثائقنا التفاعلية تجربة النقاط الطرفية، وعرض المخططات، وفهم هياكل الاستجابة مباشرة من متصفحك.
TurkeySMS Swagger V4
متوافقة تماماً مع مواصفات OpenAPI 3.0. جرب إرسال SMS، OTP، والتقارير دون كتابة سطر كود واحد.
تشغيل الوثائق التفاعلية ←
ارتقِ بتجربة عملائك
يمنحك الربط البرمجي مع TurkeySMS تحكماً كاملاً لإنشاء قنوات اتصال ذكية ومباشرة. من إرسال تنبيهات الأنظمة اللحظية إلى توثيق الهوية عبر OTP، نحن نوفر لك العمود الفقري لاتصالاتك البرمجية بأعلى معايير الأمان المتبعة دولياً.
المتطلبات
لضمان تجربة ربط ناجحة وامتثالاً للقواعد التنظيمية، يرجى التأكد من استيفاء المتطلبات التالية:
تفعيل الحساب (E-imza)
يتطلب تفعيل الحساب في تركيا وجود توقيع إلكتروني (E-imza) معتمد لإتمام الإجراءات القانونية والموافقة على الخدمة.
رصيد رسائل
يجب توفر رصيد (Credits) في حسابكم لتتمكن الواجهة البرمجية من معالجة طلبات الإرسال بنجاح.
عنوان إرسال (Sender ID)
يجب الحصول على موافقة مسبقة لعنوان الإرسال (Title) ليظهر بجانب رسائلك لدى المستلمين.
بدء سريع
ابدؤوا بإرسال أول رسالة في 3 خطوات فقط:
⚡ أسرع طريقة للبدء
التحقق من الهوية
يتم التحقق من الهوية باستخدام مفتاح الـ API الفريد الخاص بك، والذي يتم إرساله ضمن جسم الطلب (JSON Body).
يمكنك الحصول على مفتاح الـ API من لوحة التحكم الخاصة بك في قسم حسابي ← إعدادات API.
فحص المصادقة والصلاحيات
واجهة احترافية تتيح لك التحقق من صحة مفتاح الـ API الخاص بك ومعرفة كافة الصلاحيات الممنوحة له (إرسال، OTP، رصيد) بالإضافة إلى حالة الحساب الحالية.
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/auth/check \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY" }'
نموذج الاستجابة (JSON)
{ "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 وضمّنوه في مشروعكم، ثم استخدموا الكود التالي:
require_once 'TurkeySmsClient.php'; $client = new TurkeySmsClient('YOUR_API_KEY'); $result = $client->sendSms('SenderID', '905xxxxxxxxx', 'مرحباً!'); if ($client->isLastSuccess()) { echo "✅ تم الإرسال! ID: " . $result['sms_id']; }
إرسال رسالة فردية
لإرسال رسالة نصية واحدة لرقم محدد عبر طريقة POST:
المعاملات (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 -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)
$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;
استجابة ناجحة
{ "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" }
شرح حقول الاستجابة
| الحقل | الوصف |
|---|---|
| result | true في حال النجاح، false في حال الفشل. |
| result_code | كود العملية (راجعوا جدول أكواد الاستجابة). |
| result_message | رسالة تشرح نتيجة العملية. |
| sms_id | المعرّف الفريد للرسالة — يمكن استخدامه لتتبع الحالة. |
| number_of_sms | عدد الرسائل (الرصيد المخصوم). |
| sms_lang | لغة محتوى الرسالة المُرسلة. |
| content_type | نوع المحتوى (Transactional / High Quality / Advertising). |
| country | الدولة التي أُرسلت إليها الرسالة. |
إرسال رمز تحقق (OTP)
الواجهة المخصصة لإرسال رموز التحقق من رقم الجوال (OTP). تتميز هذه الواجهة بالسرعة الفائقة وإعطائها الأولوية القصوى في تسليم الرسائل.
المعاملات (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 -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)
$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;
استجابة ناجحة
{ "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 داخل النص ليتم استبداله بالرمز برمجياً.
المعاملات (Parameters)
| المعامل | النوع | الحالة | الوصف |
|---|---|---|---|
| api_key | string | إلزامي | مفتاح API الخاص بك. |
| mobile | string | إلزامي | رقم المستلم بالصيغة الدولية (مثال: 905xxxxxxxxx). |
| title | string | إلزامي | اسم المرسل (Sender ID) الخاص بك والمفعل بحسابك. |
| text | string | إلزامي | محتوى الرسالة. ملاحظة: يجب وضع TS-CODE في مكان ظهور كود الـ OTP واستخدام TS-L للنزول لسطر جديد. |
| lang | int | اختياري | لغة النص: 0 إنكليزي، 1 تركي، 2 عربي. الافتراضي: 2 |
| digits | int | اختياري | عدد خانات الكود المُولد (4، 5، أو 6). الافتراضي: 4 |
| report | int | اختياري | 1 لظهور تقرير الرد، 0 لإخفائه. الافتراضي: 1 |
| response_type | string | اختياري | نوع الرد: json أو php. الافتراضي: json |
نموذج الاستجابة (JSON)
{ "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)
المعاملات: api_key، group_name.
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)
المعاملات: api_key، group_id.
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)
المعاملات: api_key، search (اختياري).
curl -X POST https://api.turkeysms.com.tr/groups/list \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "search": "Team" }'
نموذج الاستجابة (قائمة المجموعات)
{ "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)
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" }'
نموذج الاستجابة (إضافة رقم)
{ "result": true, "result_code": "TS-1100", "result_message": "Contact added successfully", "total_added": 1, "total_failed": 0, "mobile": "905050300074" }
إرسال رسالة مجدولة
يمكنكم جدولة رسالة ليتم إرسالها في تاريخ ووقت محددين. يُستخدم نفس الرابط مع إضافة معاملات الجدولة.
معاملات الجدولة الإضافية
| المعامل | النوع | الحالة | الوصف |
|---|---|---|---|
| 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 -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)
$client = new TurkeySmsClient('YOUR_API_KEY'); $result = $client->sendScheduledSms( 'CompanyName', // عنوان الإرسال '905xxxxxxxxx', // رقم المستقبل 'ستصل هذه الرسالة في الموعد المحدد', '2026-12-31', // التاريخ '09:00', // الوقت 2 // عربي );
استجابة ناجحة
{ "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. إرسال نص موحد لمجموعة أرقام
إرسال رسالة واحدة ثابتة لمجموعة من الأرقام (مصفوفة أرقام).
2. إرسال نصوص متعددة لأرقام متعددة
إرسال نصوص مخصصة ومختلفة لمجموعة من الأرقام بحيث يتطابق ترتيب النص مع ترتيب الرقم في المصفوفة.
نموذج الطلب (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 -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"] }'
مثال على الطلب
$client = new TurkeySmsGroupClient('YOUR_API_KEY'); // إرسال نص موحد لعدة أرقام $result = $client->sendSingleTextToMultipleNumbers( 'SenderID', // عنوان المُرسل 'نص الرسالة الموحد للجميع', // النص ['905000000001', '905000000002'] // مصفوفة الأرقام ); // إرسال نصوص متعددة مخصصة $multiResult = $client->sendMultipleTextsToMultipleNumbers( 'SenderID', ['أهلاً أحمد', 'أهلاً محمد'], ['905000000001', '905000000002'] );
مثال على استجابة الإرسال الجماعي
{ "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 الخاص بك من لوحة التحكم.
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/balance/ \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY" }'
مثال على استجابة الرصيد
{ "result": true, "result_code": "TS-1040", "result_message": "operation_success", "local_balance_sms": 5400, "international_balance_tl": 30.50 }
استخدام مكتبة SDK (PHP)
$client = new TurkeySmsBalanceClient('YOUR_API_KEY'); $result = $client->checkBalance(); if (!empty($result['result'])) { echo "رصيد الرسائل المحلية: " . $result['local_balance_sms']; }
الاستعلام عن عناوين الإرسال
تسمح هذه الواجهة بالاستعلام عن قائمة عناوين الإرسال (Sender IDs) المفعلة في حسابكم. يجب تفعيل خيار الاستعلام عن العناوين من إعدادات مفتاح الـ API في لوحة التحكم.
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/senderid/check \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY" }'
مثال باستخدام 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);
نموذج الاستجابة الناجحة
{ "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)
يعرض إحصائيات عامة عن الإرسالية مثل عدد الرسائل الناجحة، الفاشلة، والمرفوضة.
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/reports/basic \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "raporid": 12345 }'
نموذج الاستجابة (تقرير أساسي)
{ "result": true, "rapor_id": 12345, "total_numbers": 1000, "success_count": 950, "failed_count": 30, "pending_count": 20 }
مثال باستخدام 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 رقم في كل صفحة.
نموذج الطلب (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_key | String | مفتاح الـ API الخاص بك. مطلوب |
raporid | Integer | رقم التقرير (ID) الذي حصلت عليه بعد عملية الإرسال. مطلوب |
page | Integer | رقم الصفحة المطلوبة (للتقرير التفصيلي فقط). الافتراضي هو 1. |
نموذج الاستجابة (تقرير تفصيلي)
{ "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)
البارامترات المطلوبة: api_key, number.
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/blacklist/add \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "number": "905xxxxxxxx" }'
نموذج الاستجابة (إضافة)
{ "status": "success", "result_code": "TS-1141", "result_message": "Number added to blacklist successfully" }
2. الاستعلام عن حالة الحظر (Check Status)
نموذج الطلب (CURL)
curl -X POST https://api.turkeysms.com.tr/blacklist/status \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "number": "905xxxxxxxx" }'
{ "status": "success", "result_code": "TS-1143", "is_blocked": true, "block_date": "2026-04-03", "block_time": "17:50" }
حالة الرسالة (SMS Status)
تسمح هذه الواجهة بالاستعلام عن حالة تسليم رسالة معينة باستخدام المعرف الفريد (SMS ID) الذي تم استلامه عند الإرسال.
البارامترات المطلوبة
| البارامتر | النوع | الوصف |
|---|---|---|
api_key | String | مفتاح الـ API الخاص بك. مطلوب |
sms_id | Integer | المعرف الفريد للرسالة المستلم من ناجيا الإرسال. مطلوب |
نموذج الطلب (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 }'
{ "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
| القيمة | اللغة | الوصف |
|---|---|---|
| 0 | English | الرسالة بالإنجليزية (GSM 7-bit encoding) |
| 1 | Türkçe | الرسالة بالتركية مع دعم الأحرف التركية الخاصة |
| 2 | العربية / Unicode | الرسالة بالعربية أو أي لغة تستخدم UTF-8 |
نوع المحتوى — content_type
| القيمة | النوع | الوصف |
|---|---|---|
| 0 | Transactional | رسالة متعلقة بعملية أو تفاعل مع المستخدم (OTP، تأكيد طلب ...) |
| 1 | High Quality | رسالة بجودة عالية — تسويقية أو إعلامية |
| 2 | Advertising | رسالة إعلانية ترويجية |
صيغة الاستجابة — response_type
| القيمة | الصيغة |
|---|---|
| json | الاستجابة بصيغة JSON (الافتراضي) |
| php | الاستجابة بصيغة PHP Array |
أكواد الاستجابة
كل عملية تُرجع كود حالة يوضح نتيجتها. استخدموا هذا الجدول لتشخيص أي مشكلة.
| الكود | HTTP | الوصف |
|---|---|---|
| TS-1072 | 400 | تكرار في أرقام الوجهة. |
| TS-1140 | 400 | الرقم محجوب مسبقاً لهذا المستخدم. |
| TS-1141 | 200 | تم إضافة الرقم للقائمة السوداء بنجاح. |
| TS-1142 | 200 | الرقم غير موجود في القائمة السوداء. |
| TS-1143 | 200 | الرقم محجوب حالياً. |
| TS-1144 | 400 | تنسيق رقم الهاتف غير صحيح. |
| TS-1080 | 200 | تم إنشاء المجموعة بنجاح. |
| TS-1081 | 403 | صلاحية إنشاء المجموعات غير مفعلة. |
| TS-1082 | 400 | اسم المجموعة موجود مسبقاً. |
| TS-1083 | 400 | اسم المجموعة غير صالح. |
| TS-1084 | 403 | صلاحية تعديل المجموعات غير مفعلة. |
| TS-1085 | 403 | صلاحية حذف المجموعات غير مفعلة. |
| TS-1086 | 404 | المجموعة غير موجودة أو غير مصرح بالوصول إليها. |
| TS-1087 | 200 | تم تعديل المجموعة بنجاح. |
| TS-1088 | 200 | تم حذف المجموعة بنجاح. |
| TS-1089 | 403 | صلاحية عرض المجموعات غير مفعلة. |
| TS-1090 | 200 | تم جلب قائمة المجموعات بنجاح. |
| TS-1024 | 200 | تم الإرسال بنجاح. |
| TS-1040 | 200 | تم الاستعلام عن الرصيد بنجاح. |
| TS-1025 | 400 | رقم المستقبل مفقود أو غير صحيح. |
| TS-1026 | 400 | نص الرسالة مفقود أو فارغ. |
| TS-1027 | 403 | الرصيد غير كافٍ لإتمام عملية الإرسال. |
| TS-1028 | 403 | عنوان الإرسال (Sender ID) غير مفعّل أو غير موثق. |
| TS-1036 | 403 | خيار إرسال الـ OTP العادي غير مفعّل لهذا المفتاح. |
| TS-1037 | 403 | خيار إرسال الـ OTP المتقدم غير مفعّل لهذا المفتاح. |
| TS-1060 | 403 | تم تجاوز حد الإرسال المسموح في الدقيقة الواحدة. |
| TS-1030 | 403 | الحساب غير مفعّل أو موقوف مؤقتاً. |
| TS-1031 | 401 | مفتاح API غير صالح أو غير مفعّل. |
| TS-1032 | 403 | خدمة الإرسال الدولي غير مفعّلة لهذا الحساب. |
| TS-1033 | 400 | صيغة البيانات المُرسلة غير صالحة (ليست JSON). |
| TS-1034 | 400 | عنوان الإرسال (title) مفقود أو يحتوي على رموز غير مسموحة. |
| TS-1050 | 401 | مفتاح API مفقود من الطلب. |
| TS-1061 | 403 | صلاحية الإرسال عبر POST غير مفعّلة لهذا المفتاح. |
| TS-1065 | 403 | صلاحيات المفتاح لا تسمح بالقيام بهذه العملية (الخدمة معطلة للحساب). |
| TS-1066 | 403 | صلاحية الإرسال الجماعي (Group Send) غير مفعّلة لهذا المفتاح. |
| TS-1072 | 400 | هناك أرقام مكررة في مصفوفة الإرسال الجماعي. |
| TS-1063 | 403 | صلاحية الاستعلام عن الحالة غير مفعلة. |
| TS-1052 | 400 | المعرف الفريد للرسالة (sms_id) مفقود. |
| TS-1064 | 200 | تم استلام الرسالة بنجاح. |
| TS-1023 | 200 | الرقم خارج التغطية، لم يتم استلام الرسالة بعد. |
| TS-1100 | 200 | تم إضافة الرقم لجهة الاتصال بنجاح. |
| TS-1101 | 400 | فشل إضافة الرقم لجهة الاتصال أو الرقم موجود مسبقاً. |
| TS-1022 | 200 | الرقم لم يستلم الرسالة (فشل التسليم). |
المكتبات البرمجية (SDK)
لبدء الدمج بسرعة قصوى، وفرنا لكم مكتبات برمجية جاهزة (SDK) ومعالجة بالكامل لأشهر لغات البرمجة. تدعم جميع المكتبات ميزات الإرسال الفوري، OTP، الإرسال المجدول، والإرسال الجماعي.
Webhooks (تقارير الإرسال اللحظية)
بدلاً من الاستعلام المتكرر عن حالة الرسائل، يوفر نظام TurkeySMS ميزة الـ Webhooks التي تقوم بدفع تقارير الإرسال المفصلة (Detailed Reports) إلى سيرفرك فور تحديثها لدى المشغل. هذا يقلل من استهلاك موارد سيرفرك ويضمن تحديث البيانات لحظياً.
تأمين الاستقبال (Signature Verification)
لضمان أن البيانات قادمة من سيرفراتنا فعلاً، نرسل في الترويسة (Header) القيمة التالية: X-TurkeySms-Signature. وهي عبارة عن تشفير لمحتوى البيانات باستخدام Secret Key الخاص بك (HMAC-SHA256).
نموذج كود استقبال (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 سابقاً). ومن خلال تطبيقنا الرسمي، يمكنك أتمتة تدفقات عمل الاتصالات الخاصة بك دون كتابة سطر واحد من الكود.
الموديولات المتاحة
- إرسال رسالة فردية: أتمتة الإشعارات والتنبيهات والتسويق.
- إرسال OTP: تسليم سريع لرموز التحقق.
- الاستعلام عن الرصيد: مراقبة رصيدك في الوقت الفعلي.
- اتصال المصادقة: أدخل مفتاح API الخاص بك بشكل آمن مرة واحدة واستخدمه عبر السيناريوهات.
كيفية الإعداد
- في سيناريو Make.com الخاص بك، قم بإضافة موديول TurkeySMS.
- انقر فوق Add Connection وقم بتسميته (على سبيل المثال، "حسابي").
- قم بلصق API Key الخاص بك من لوحة تحكم TurkeySMS.
- قم بتكوين معلمات الموديول الخاص بك وابدأ الأتمتة!
التكامل (Integrations)
نحن نوفر حلولاً جاهزة للدمج مع أشهر المنصات العالمية لتسهيل تجربة الاستخدام دون الحاجة لكتابة كود برمجي معقد.