API SYRIA – API Documentation

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

نظرة عامة

تعتمد جميع الطلبات على نفس عنوان الأساس (Base URL)، ويتم استخدام api_key للمصادقة على الطلبات. يحصل كل مستخدم على مفتاح خاص من صفحة إعدادات الـ 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) فحص حالة الـ APIGETresource=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" }}
2) جلب الحسابات المرتبطةGETresource=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": [ { "id": 1, "gsm": "0933xxxxxx", "is_verified": 1, "last_balance": "150000", "last_balance_at": "2025-01-01 12:30:00" } ], "shamcash": [ { "id": 2, "account_address": "محفظة رئيسية", "created_at": "2025-01-01 10:00:00" } ] }}
3) Syriatel Cash – جلب الرصيدGETresource=syriatel & action=balance

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

https://apisyria.com/api/v1?resource=syriatel&action=balance&gsm=0933xxxxxx&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • gsm (إجباري) – رقم الهاتف المحمول.
  • api_key (إجباري).
مثال على الاستجابة:
{ "success": true, "data": { "gsm": "0933xxxxxx", "balance": "150000", "last_balance_at": "2025-01-01 12:40:00" }}
4) Syriatel Cash – سجلات العملياتGETresource=syriatel & action=history

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

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.
  • api_key (إجباري).
مثال مختصر على الاستجابة:
{ "success": true, "data": { "gsm": "0933xxxxxx", "period": "7", "items": [ { "transaction_no": "123456789", "date": "2025-01-01 11:20:00", "from": "0933xxxxxx", "to": "0944yyyyyy", "amount": "25000" } ] }}
5) ShamCash – سجلات التحويلات (tranKind = 1)GETresource=shamcash & action=logs

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

https://apisyria.com/api/v1?resource=shamcash&action=logs&account_address=251aw******************&api_key=YOUR_API_KEY_HERE
المعاملات (Parameters):
  • account_address (اختياري) – اسم الحساب كما أُضيف في المنصّة.
  • account_id (اختياري) – رقم الـ ID الخاص بالحساب في قاعدة البيانات.
  • api_key (إجباري).
مثال على الاستجابة:
{ "success": true, "data": { "account_id": 2, "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": "123-456-789", "note": "شحن رصيد", "tran_kind": 1 } ] }}
6) ShamCash – جلب رصيد الحسابGETresource=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 (اختياري) – اسم الحساب كما أضفته في لوحة التحكم (الحقل: "اسم الحساب").
  • account_id (اختياري) – رقم الـ ID للحساب من Endpoint accounts&action=list.
  • api_key (إجباري).
  • يجب إرسال واحد على الأقل من account_address أو account_id.
مثال على الاستجابة (نفس الشكل اللي ورجيتني من ShamCash تقريباً لكن مبسّط):
{ "success": true, "data": { "account_id": 2, "account_address": "251aw******************", "balances": [ { "currency": "USD", "balance": 0 }, { "currency": "SYP", "balance": 20980 }, { "currency": "TRY", "balance": 0 } ] }}

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

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

  • 400طلب غير مكتمل أو يحتوي على معاملات ناقصة (مثل عدم إرسال gsm أو account_address).
  • 401مشكلة في المصادقة – غالبًا مفتاح الـ API غير مُرسل أو غير صحيح.
  • 403غير مسموح بالوصول – مثال: مفتاح الـ API موقوف أو عنوان الـ IP غير مخوَّل باستخدام هذا المفتاح.
  • 404نقطة نهاية غير معروفة أو الحساب المطلوب غير موجود للمستخدم.
  • 405طريقة HTTP غير مدعومة (حاليًّا جميع النقاط تعتمد على GET فقط).
  • 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 مرتبط بهذا الرقم لهذا المستخدم." }