SMS API للمطورين في الأردن: أرسل رسائل التحقق والإشعارات من كودك

إذا كنت تبني موقعاً أو تطبيقاً أو نظاماً داخلياً في الأردن، فغالباً ستحتاج إلى إرسال رسائل قصيرة تلقائية: رمز تحقق عند التسجيل، أو تأكيد طلب، أو تذكير بموعد. في هذا الدليل نشرح كيف تربط نظامك بواجهة SMS API من منصة sms-jo خطوة بخطوة، مع أمثلة جاهزة بلغات البرمجة الشائعة.

لماذا ترسل الرسائل القصيرة من الكود مباشرة؟

• رموز التحقق OTP: للتسجيل وتسجيل الدخول واستعادة كلمة المرور وتأكيد المدفوعات.
• إشعارات الطلبات: تأكيد الطلب وخروجه للتوصيل ووصوله.
• تنبيهات الأنظمة: إبلاغ فريقك فوراً عند حدوث خلل.
• تذكير المواعيد: مع إمكانية جدولة الإرسال لوقت محدد.

الرسالة القصيرة تصل إلى أي جوال دون إنترنت ودون تطبيق، ولهذا تبقى الخيار الأوثق للرسائل الحساسة للوقت.

قبل أن تبدأ

1. أنشئ حساباً على منصة sms-jo واختر باقة تتضمن الوصول إلى API.
2. اطلب اسم مرسل وانتظر اعتماده. يُكتب اسم المرسل بالحروف والأرقام الإنجليزية فقط، بحد أقصى 11 خانة بما فيها الفراغ.
3. أنشئ API Token من قسم المطورين في لوحة التحكم، واحفظه في متغيرات البيئة على الخادم، ولا تضعه أبداً في كود الواجهة الأمامية.

معاملات الطلب

يُرسل الطلب بصيغة JSON عبر HTTPS إلى نقطة النهاية POST /api/v3/sms/send، مع ترويسة Authorization: Bearer:

• recipient: رقم واحد، أو عدة أرقام مفصولة بفواصل، بالصيغة الدولية دون + ودون أصفار بادئة، مثل 9627XXXXXXXX.
• sender_id: اسم المرسل المعتمد.
• type: plain للنص الإنجليزي، وunicode للنص العربي.
• message: نص الرسالة.
• schedule_time: اختياري، لجدولة الإرسال.

مثال: cURL

curl -X POST https://sms-jo.com/api/v3/sms/send \
  -H "Authorization: Bearer $SMSJO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"recipient":"9627XXXXXXXX","sender_id":"MyBrand","type":"unicode","message":"رمز التحقق: 4821"}'

مثال: PHP

<?php
$ch = curl_init('https://sms-jo.com/api/v3/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SMSJO_TOKEN'),
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'recipient' => '9627XXXXXXXX',
        'sender_id' => 'MyBrand',
        'type'      => 'unicode',
        'message'   => 'تم تأكيد طلبك رقم 1052',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

مثال: Node.js

const res = await fetch('https://sms-jo.com/api/v3/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SMSJO_TOKEN}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    recipient: '9627XXXXXXXX',
    sender_id: 'MyBrand',
    type: 'plain',
    message: 'Your code is 4821'
  })
});
const data = await res.json();

مثال: Python

import os, requests

r = requests.post(
    "https://sms-jo.com/api/v3/sms/send",
    headers={"Authorization": f"Bearer {os.environ['SMSJO_TOKEN']}",
             "Accept": "application/json"},
    json={"recipient": "9627XXXXXXXX", "sender_id": "MyBrand",
          "type": "unicode", "message": "موعدك غداً الساعة 10 صباحاً"},
)
print(r.json())

نقاط نهاية أخرى مفيدة

• GET /api/v3/balance: الرصيد المتبقي، وافحصه قبل الحملات الكبيرة.
• GET /api/v3/sms: سجل الرسائل المرسلة.
• GET /api/v3/me: بيانات الحساب.
• POST /api/v3/contacts/{group_id}/store: إضافة رقم إلى مجموعة جهات اتصال.

وإن كان نظامك لا يستطيع إرسال الترويسات، فهناك نقطة نهاية بديلة /api/http/sms/send تستقبل api_token كمعامل.

أفضل الممارسات

• اختصر رسائل OTP: الرسالة العربية تتسع لسبعين حرفاً، وما زاد يُحتسب أجزاء إضافية من الرصيد.
• اذكر اسم الخدمة ومدة صلاحية الرمز في نص رسالة التحقق.
• حدّد عدد طلبات الرمز لكل رقم لحماية رصيدك من الإساءة.
• وحّد صيغة الأرقام قبل الإرسال: احذف + والصفر البادئ.
• لا تكشف الـ Token في المتصفح أو تطبيق الجوال؛ أرسل دائماً من خادمك.

ابدأ الآن

راجع التوثيق الكامل للمطورين، واطّلع على الأسئلة الشائعة، أو اقرأ عن رسائل التحقق OTP والرسائل القصيرة الجماعية. وإن كنت تدير الحملات التسويقية أيضاً، فصفحة الرسائل القصيرة للمسوقين تناسبك، ويمكنك المتابعة من جوالك عبر تطبيق المنصة.