SMS API في سوريا: دليل المطور لإرسال رموز التحقق

المصادقة

كل طلب يحتاج ترويستين: مفتاح الـ API في Authorization: Bearer، والوقت الحالي بالثواني (Unix) في X-Timestamp. يُرفض الطلب إذا كان الوقت مختلفاً عن وقت الخادم بأكثر من 5 دقائق، وهذا يحمي من إعادة إرسال الطلبات.

# إرسال رمز تحقق إلى رقم سوري
curl -X POST https://sms.msgplus.tech/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_name": "MyApp",
    "template_id": 1,
    "numbers": ["963941234567"],
    "vars": { "code": "482916" }
  }'

نقاط الـ API

صيغ الأرقام السورية المقبولة

يقبل الـ API الصيغ الشائعة ويحوّلها تلقائياً إلى الصيغة الدولية 9639XXXXXXXX قبل الإرسال إلى سيريتل. يمكن أن تحتوي الأرقام على مسافات أو شرطات أو أرقام عربية.

الترميز وطول الرسالة

• الرسائل العربية تُرسل بترميز Unicode: 70 حرفاً للجزء الواحد، و67 حرفاً لكل جزء في الرسائل الطويلة.
• الرسائل الإنجليزية بترميز GSM-7: 160 حرفاً للجزء الواحد.
• التكلفة = عدد الأرقام × عدد الأجزاء، لذا اجعل قالب الرمز قصيراً ليبقى في جزء واحد.
• استخدم POST /api/v1/sms/estimate لمعرفة عدد الأجزاء قبل الإرسال.

رموز الأخطاء

نصائح للإنتاج

• أرسل من خادمك فقط، ولا تضع مفتاح الـ API داخل تطبيق الجوال.
• زامن ساعة الخادم (NTP) لتجنب أخطاء X-Timestamp.
• جرّب أولاً في وضع Sandbox: رسائل محاكاة لا تُرسل ولا تستهلك الرصيد.
• الرسائل الفاشلة يُعاد رصيدها تلقائياً، ويمكنك متابعة كل رقم من سجل الإرسال.