API SYRIA – API Documentation

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

نظرة عامة

جميع الطلبات تتم عبر نفس عنوان الأساس (Base URL) ويُستخدم api_key للمصادقة على الطلبات. يحصل كل مستخدم على مفتاح API خاص به من صفحة إعدادات الـ API داخل حسابه في الموقع.

عنوان الـ API الأساسي (API Base URL):
https://apisyria.sy/api/v1
يرجى استبدال YOUR_API_KEY_HERE بمفتاح الـ API الخاص بك من صفحة إعدادات الـ API في حسابك.

بداية سريعة

يجب أن يحتوي كل طلب على مفتاح الـ API، إما من خلال معامل في الرابط (Query String) أو من خلال ترويسة (Header).

1. باستخدام Query String:
GET https://apisyria.sy/api/v1?resource=status&api_key=YOUR_API_KEY_HERE
2. باستخدام ترويسة (Header) – (مُفضّل):
GET https://apisyria.sy/api/v1?resource=status
X-Api-Key: YOUR_API_KEY_HERE
مثال باستخدام cURL:
curl -X GET \ "https://apisyria.sy/api/v1?resource=status" \ -H "X-Api-Key: YOUR_API_KEY_HERE" \ -H "Accept: application/json"
مثال بسيط بلغة PHP:
$ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => "https://apisyria.sy/api/v1?resource=status", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "X-Api-Key: YOUR_API_KEY_HERE", "Accept: application/json", ], ]); $response = curl_exec($ch); curl_close($ch); echo $response;

نقاط النهاية (Endpoints) المتاحة

1) فحص حالة الـ API GET resource=status

تُستخدم هذه النقطة للتحقق من أن واجهة الـ API تعمل بشكل صحيح، كما تُرجع معلومات أساسية عن المستخدم المرتبط بمفتاح الـ API، بالإضافة إلى معلومات عن حدود الحساب.

https://apisyria.sy/api/v1?resource=status&api_key=YOUR_API_KEY_HERE
مثال على الاستجابة:
{ "success": true, "message": "API is working.", "user": { "id": 123, "name": "User Name", "email": "user@example.com" }, "limits": { "max_linked_accounts": 10 } }
2) جلب الحسابات المرتبطة الفعّالة GET resource=accounts & action=list

تُرجع هذه النقطة جميع حسابات Syriatel Cash و ShamCash الفعّالة المرتبطة بحساب المستخدم صاحب مفتاح الـ API، وذلك ضمن الحد الأقصى المسموح به في الباقة الحالية.

https://apisyria.sy/api/v1?resource=accounts&action=list&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • api_key (إجباري).
مثال مختصر على الاستجابة:
{ "success": true, "data": { "syriatel": [ { "gsm": "0933xxxxxx", "cash_code": "123456" } ], "shamcash": [ { "account_address": "251a***********************e" } ] } }

ملاحظة: يتم إرجاع الحقول الأساسية فقط:
– gsm و cash_code لحسابات Syriatel Cash.
– account_address لحسابات ShamCash.
التفاصيل الأخرى (مثل الرصيد والسجلات) يمكن جلبها عبر نقاط النهاية المتخصصة.

3) Syriatel Cash – جلب الرصيد GET resource=syriatel & action=balance

تُستخدم هذه النقطة لجلب رصيد رقم Syriatel Cash معيّن، بشرط أن يكون الرقم مضافًا ومُوثَّقًا ضمن حساب المستخدم على المنصّة وأن يكون ضمن الحد المسموح به في باقته.

يمكن تمرير رقم الموبايل أو كود الكاش في نفس المعامل gsm.

https://apisyria.sy/api/v1?resource=syriatel&action=balance&gsm=0933xxxxxx&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • gsm (إجباري) – يمكن أن يكون:
    • رقم الهاتف المحمول (مثال: 0933xxxxxx)
    • أو كود الكاش المخزَّن للحساب نفسه.
  • api_key (إجباري).
مثال على الاستجابة:
{ "success": true, "data": { "gsm": "0933xxxxxx", "cash_code": "123456", "balance": "150000" } }
4) Syriatel Cash – سجلات العمليات GET resource=syriatel & action=history

تُستخدم هذه النقطة لجلب سجل عمليات Syriatel Cash لرقم معيّن، مع إمكانية تحديد الفترة الزمنية للبحث.

تماماً كما في جلب الرصيد، يمكن تمرير رقم الموبايل أو كود الكاش في المعامل gsm.

https://apisyria.sy/api/v1?resource=syriatel&action=history&gsm=0933xxxxxx&period=7&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • gsm (إجباري) – رقم الهاتف المحمول أو كود الكاش المخزَّن للحساب.
  • period (اختياري) – القيم المدعومة: 7 أو 30 أو all. الافتراضي هو 7 أيام.
  • api_key (إجباري).
مثال مختصر على الاستجابة:
{ "success": true, "data": { "gsm": "0933xxxxxx", "cash_code": "123456", "period": "7", "items": [ { "transaction_no": "123456789", "date": "2025-01-01 11:20:00", "from": "0933xxxxxx", "to": "0944yyyyyy", "amount": "25000" } ] } }
5) Syriatel Cash – البحث عن عملية برقم العملية GET resource=syriatel & action=find_tx

تُستخدم هذه النقطة للبحث عن عملية Syriatel Cash محددة عن طريق رقم العملية كما يظهر في تطبيق سيريتل كاش. يتم البحث ضمن حساب واحد محدد فقط، ويجب إرسال الباراميتر gsm، والذي يمكن أن يكون رقم الموبايل أو كود الكاش.

https://apisyria.sy/api/v1?resource=syriatel&action=find_tx&tx=123456&gsm=0933xxxxxx&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • tx (إجباري) – رقم العملية transaction_no كما يظهر في تطبيق سيريتل كاش. يجب أن يكون أرقام فقط (بين 3 و 30 خانة تقريبًا).
  • gsm (إجباري)
    • يمكن أن يكون رقم الهاتف (مثال: 0933xxxxxx)
    • أو كود الكاش المخزَّن لنفس الحساب.
  • period (اختياري) – نفس منطق history: 7 أو 30 أو all، والافتراضي 7 أيام.
  • api_key (إجباري).
مثال
GET https://apisyria.sy/api/v1?resource=syriatel&action=find_tx&tx=123456&gsm=0933xxxxxx&api_key=YOUR_API_KEY_HERE
مثال استجابة عند إيجاد العملية:
{ "success": true, "data": { "found": true, "transaction": { "transaction_no": "123456", "date": "2025-01-01 11:20:00", "from": "0933xxxxxx", "to": "0944yyyyyy", "amount": "25000" }, "account": { "gsm": "0933xxxxxx", "cash_code": "ABC123" } } }
مثال استجابة عند عدم العثور على العملية:
{ "success": true, "data": { "found": false, "transaction_no": "123456" } }

ملاحظة:
– القيمة found تكون true إذا تم العثور على العملية و false إذا لم يتم العثور على أي عملية مطابقة ضمن الحساب المحدد والفترة الزمنية.

6) Syriatel Cash – تحويل كاش POST resource=syriatel & action=transfer_cash

تُستخدم هذه النقطة لتنفيذ عملية تحويل Syriatel Cash من حساب مصدر مرتبط بالمستخدم إلى رقم مستفيد آخر، بعد إجراء فحص المستفيد تلقائيًا ثم تنفيذ عملية التحويل.

هذه عملية حساسة، لذلك يجب إرسالها باستخدام POST وليس GET.

POST https://apisyria.sy/api/v1?resource=syriatel&action=transfer_cash
المعاملات (Parameters) – POST:
  • gsm (إجباري) – رقم الحساب المصدر أو كود الكاش.
  • to_gsm (إجباري) – رقم المستفيد المراد التحويل إليه.
  • amount (إجباري) – مبلغ التحويل.
  • pin_code (إجباري) – رمز PIN الخاص بحساب سيريتل كاش.
  • api_key (إجباري) – يمكن إرساله Header أو Query String.
مثال باستخدام cURL:
curl -X POST \ "https://apisyria.sy/api/v1?resource=syriatel&action=transfer_cash" \ -H "X-Api-Key: YOUR_API_KEY_HERE" \ -H "Accept: application/json" \ -d "gsm=0933xxxxxx" \ -d "to_gsm=0995xxxxxxx" \ -d "amount=100" \ -d "pin_code=1234"
مثال استجابة ناجحة:
{ "success": true, "data": { "source_account": { "gsm": "0933xxxxxx", "cash_code": "123456" }, "beneficiary": { "gsm": "0995xxxxxxx" }, "amount": "100", "fee": "5", "billcode": "ABCDEF123", "message": "تم التحويل بنجاح", "raw": {} } }
7) Syriatel Mobile – شحن رصيد موبايل POST resource=syriatel & action=mobile_recharge

تُستخدم هذه النقطة لشحن رصيد موبايل Syriatel (مسبق الدفع) من حساب Syriatel Cash مرتبط بالمستخدم. تعتمد هذه النقطة على فئات الشحن وليس على إرسال مبلغ عشوائي مباشرة.

أرسل قيمة category كما هي من نقطة recharge_categories (مثال 1.92)، وسيقوم الخادم بتحويلها تلقائيًا إلى المبلغ الفعلي المناسب لسيريتل (مثال 2).
كما يدعم الخادم أيضًا الاسم القديم recharge_amount بدل category للتوافق.

POST https://apisyria.sy/api/v1?resource=syriatel&action=mobile_recharge
المعاملات (Parameters) – POST:
  • gsm (إجباري) – رقم الحساب المصدر أو كود الكاش.
  • target_gsm (إجباري) – رقم سيريتل المراد شحنه.
  • category (إجباري) – قيمة الفئة من recharge_categories (مثل 1.92).
  • pin_code (إجباري) – رمز PIN الخاص بحساب سيريتل كاش.
  • api_key (إجباري) – يمكن إرساله Header أو Query String.
القيم المتاحة للحقل category (select_value فقط):

استخدم إحدى القيم التالية مباشرةً في الحقل category.

1.92, 2.88, 3.84, 4.80, 5.76, 9.61, 20.19, 23.07, 24.03, 25.96, 30.76, 40.38, 45.19, 48.07, 52.88, 62.5, 68.26, 72.11, 77.88, 81.73, 86.53, 96.15, 100.96, 105.76, 115.38, 125, 125.00, 130.76, 144.23, 160.57, 163.46, 173.07, 183.65, 192.30, 211.53, 240.38, 288.46, 317.30, 370.19, 432.69, 480.76, 576.92, 625, 625.00, 721.15, 769.23, 951.92, 1057.69, 1250, 1250.00, 1923.07, 2115.38, 2403.84, 3846.15
مثال باستخدام cURL:
curl -X POST \ "https://apisyria.sy/api/v1?resource=syriatel&action=mobile_recharge" \ -H "X-Api-Key: YOUR_API_KEY_HERE" \ -H "Accept: application/json" \ -d "gsm=0933xxxxxx" \ -d "target_gsm=0998xxxxxxx" \ -d "category=1.92" \ -d "pin_code=1234"
مثال استجابة ناجحة:
{ "success": true, "data": { "source_account": { "gsm": "0933xxxxxx", "cash_code": "123456" }, "target_gsm": "0998xxxxxxx", "selected_category": "1.92", "sent_amount": "2", "recharge_amount": "2", "fee_amount": "0", "tax": "0", "bill_code": "123456789", "message": "تم الشحن بنجاح", "raw": {} } }
8) ShamCash – سجلات التحويلات GET resource=shamcash & action=logs

تُستخدم هذه النقطة لجلب جميع التحويلات لحساب ShamCash محدّد، استنادًا إلى الحسابات المرتبطة بالمستخدم داخل المنصّة. يتم إرجاع معلومات العملية بما فيها رقم العملية، اسم المرسِل، المستفيد، العملة، المبلغ، التاريخ والوقت، حساب المرسِل في شام كاش، والملاحظة.

https://apisyria.sy/api/v1?resource=shamcash&action=logs&account_address=251aw******************&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • account_address عنوان حساب شام كاش (إجباري).
  • api_key (إجباري).
مثال على الاستجابة:
{ "success": true, "data": { "account_address": "251aw******************", "items": [ { "tran_id": "987654321", "from_name": "Client Name", "to_name": "Your Name", "currency": "SYP", "amount": 25000, "datetime": "2025-01-01 10:15:00", "account": "251aw******************", "note": "شحن رصيد" } ] } }
9) ShamCash – جلب رصيد الحساب GET resource=shamcash & action=balance

تُستخدم هذه النقطة لجلب رصيد حساب ShamCash المرتبط بحسابك على المنصّة. يتم إرجاع جميع العملات المتاحة مع الرصيد الخاص بكل عملة (مثل USD، SYP، EUR).

https://apisyria.sy/api/v1?resource=shamcash&action=balance&account_address=251aw******************&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • account_address عنوان حساب شام كاش (إجباري).
  • api_key (إجباري).
مثال على الاستجابة:
{ "success": true, "data": { "account_address": "251aw******************", "balances": [ { "currency": "USD", "balance": 0 }, { "currency": "SYP", "balance": 20980 }, { "currency": "EUR", "balance": 0 } ] } }
10) ShamCash – البحث عن عملية برقم العملية GET resource=shamcash & action=find_tx

تُستخدم هذه النقطة للبحث عن عملية ShamCash محدّدة عن طريق رقم العملية كما يظهر في تطبيق شام كاش. يتم البحث ضمن حساب واحد محدد فقط، ويجب إرسال account_address لتحديد الحساب المراد البحث ضمنه.

https://apisyria.sy/api/v1?resource=shamcash&action=find_tx&tx=987654321&account_address=251aw******************&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • tx (إجباري) – رقم العملية كما يظهر في سجل العمليات في شام كاش. يجب أن يكون أرقام فقط (من 3 إلى 30 خانة تقريبًا).
  • account_address (إجباري) – عنوان حساب شام كاش (مثل 251aw******************).
  • api_key (إجباري).
مثال
GET https://apisyria.sy/api/v1?resource=shamcash&action=find_tx&tx=987654321&account_address=251aw******************&api_key=YOUR_API_KEY_HERE
مثال استجابة عند إيجاد العملية:
{ "success": true, "data": { "found": true, "transaction": { "tran_id": "987654321", "from_name": "Client Name", "to_name": "Your Name", "currency": "SYP", "amount": 25000, "datetime": "2025-01-01 10:15:00", "account": "251aw******************", "note": "شحن رصيد" }, "account": { "account_address": "251aw******************", } } }
مثال استجابة عند عدم العثور على العملية:
{ "success": true, "data": { "found": false, "tran_id": "987654321" } }

ملاحظات:
– الحقل found يكون true في حال العثور على عملية مطابقة، و false إذا لم يتم العثور على أي عملية بهذا الرقم ضمن الحساب التي تم البحث فيه.
– الحقول داخل transaction مطابقة تقريبًا لنقطة النهاية shamcash&action=logs لتسهيل الربط بينهما.

أخطاء شائعة وكيفية قراءتها

أكواد HTTP المستخدمة

  • 400 طلب غير مكتمل أو يحتوي على معاملات ناقصة (مثل عدم إرسال gsm أو account_address).
  • 401 مشكلة في المصادقة – غالبًا مفتاح الـ API غير مُرسل أو غير صحيح.
  • 403 غير مسموح بالوصول – مثال: الحساب المطلوب غير مفعّل ضمن باقتك الحالية أو مفتاح الـ API موقوف.
  • 404 نقطة نهاية غير معروفة أو الحساب المطلوب غير موجود للمستخدم.
  • 405 طريقة HTTP غير مدعومة (حاليًّا جميع النقاط تعتمد على GET فقط).
  • 429 تم تجاوز حد عدد الطلبات المسموح به خلال فترة زمنية قصيرة (Rate Limit) – الرجاء الانتظار قبل إعادة المحاولة.
  • 500 خطأ داخلي في الخادم داخل المنصّة نفسها.
  • 502 خطأ من مزوّد الخدمة الخارجي (Syriatel أو ShamCash) أثناء جلب البيانات.
شكل استجابة خطأ قياسي:
{ "success": false, "error": "رسالة الخطأ بالعربية" }
مثال 401 – عدم إرسال مفتاح الـ API:
HTTP 401 Unauthorized { "success": false, "error": "Missing API key. استخدم X-Api-Key أو ?api_key=" }
مثال 404 – حساب غير موجود:
HTTP 404 Not Found { "success": false, "error": "لا يوجد حساب Syriatel مرتبط بهذا الرقم أو كود الكاش لهذا المستخدم." }
مثال 429 – تجاوز عدد الطلبات (Rate Limit):
HTTP 429 Too Many Requests { "success": false, "error": "تم تجاوز الحد المسموح للطلبات. حاول مرة أخرى بعد قليل.", "retry_after": 30 }