API SYRIA – API Documentation

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

نظرة عامة

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

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

بداية سريعة

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

1. باستخدام Query String:
GET https://apisyria.com/api/v1?resource=status&api_key=YOUR_API_KEY_HERE
2. باستخدام ترويسة (Header) – (مُفضّل):
GET https://apisyria.com/api/v1?resource=status
X-Api-Key: YOUR_API_KEY_HERE
مثال باستخدام cURL:
curl -X GET \ "https://apisyria.com/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.com/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.com/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.com/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.com/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.com/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 محددة عن طريق رقم العملية (transaction_no) كما يظهر في تطبيق سيريتل كاش. يمكن البحث ضمن كل الحسابات المفعّلة للمستخدم، أو حصر البحث بحساب واحد (رقم موبايل أو كود كاش).

https://apisyria.com/api/v1?resource=syriatel&action=find_tx&tx=123456&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • tx (إجباري) – رقم العملية transaction_no كما يظهر في تطبيق سيريتل كاش. يجب أن يكون أرقام فقط (بين 3 و 30 خانة تقريبًا).
  • gsm (اختياري) – إذا أرسلته، يتم حصر البحث بحساب واحد فقط:
    • يمكن أن يكون رقم الهاتف (مثال: 0933xxxxxx)
    • أو كود الكاش المخزَّن لنفس الحساب.
    إذا لم ترسله، يتم البحث في جميع حسابات Syriatel المفعّلة والموثقة الخاصة بالمستخدم.
  • period (اختياري) – نفس منطق history: 7 أو 30 أو all، والافتراضي 7 أيام.
  • api_key (إجباري).
مثال – البحث ضمن جميع حسابات Syriatel المفعّلة:
GET https://apisyria.com/api/v1?resource=syriatel&action=find_tx&tx=123456&api_key=YOUR_API_KEY_HERE
مثال – حصر البحث بحساب معيّن (رقم أو كود كاش):
GET https://apisyria.com/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 إذا لم يتم العثور على أي عملية مطابقة ضمن الحسابات المحددة والفترة الزمنية.
– الحقل account يوضح أي حساب Syriatel (رقم الموبايل + كود الكاش إن وجد) تم العثور على العملية ضمنه.

5) ShamCash – سجلات التحويلات GET resource=shamcash & action=logs

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

https://apisyria.com/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": "شحن رصيد" } ] } }
6) ShamCash – جلب رصيد الحساب GET resource=shamcash & action=balance

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

https://apisyria.com/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": "TRY", "balance": 0 } ] } }
7) ShamCash – البحث عن عملية برقم العملية GET resource=shamcash & action=find_tx

تُستخدم هذه النقطة للبحث عن عملية ShamCash محدّدة عن طريق رقم العملية (tran_id) كما يظهر في تطبيق شام كاش. يمكن البحث ضمن كل حسابات شام كاش المفعّلة المرتبطة بحسابك، أو حصر البحث بحساب واحد فقط.

https://apisyria.com/api/v1?resource=shamcash&action=find_tx&tx=123456&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • tx (إجباري) – رقم العملية tran_id كما يظهر في سجل العمليات في شام كاش. يجب أن يكون أرقام فقط (من 3 إلى 30 خانة تقريبًا).
  • account_address (اختياري) – عنوان حساب شام كاش (مثل 251aw******************).
  • إذا لم يتم إرسال account_address، سيتم البحث في جميع حسابات ShamCash المفعّلة المرتبطة بنفس المستخدم.
  • api_key (إجباري).
مثال – البحث في كل حسابات ShamCash المفعّلة:
GET https://apisyria.com/api/v1?resource=shamcash&action=find_tx&tx=987654321&api_key=YOUR_API_KEY_HERE
مثال – حصر البحث بحساب معيّن باستخدام account_address:
GET https://apisyria.com/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 إذا لم يتم العثور على أي عملية بهذا الرقم ضمن الحسابات التي تم البحث فيها.
– الحقل account يوضّح أي حساب ShamCash (عنوان الحساب) تم العثور على العملية ضمنه.
– الحقول داخل 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 }