توثيق الـ API

واجهة برمجية موحّدة لحسابات سيرياتيل كاش وشام كاش التي ربطتها على هذه المنصة: الأرصدة، السجلات، البحث عن العمليات والتحويلات، بصيغة JSON وبالمخرجات نفسها التي يعيدها apisyria.com.

كل الردود JSON بترميز UTF-8. النجاح: "success": true، والخطأ: "success": false مع "error" بالعربية.

المصادقة

لكل محاسب مفتاحه من صفحة إعدادات الـ API. أرسله في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.

GET https://api.eaglebot99.com?resource=status
X-Api-Key: YOUR_API_KEY

GET https://api.eaglebot99.com?resource=status&api_key=YOUR_API_KEY

سجّل الدخول (أو أنشئ حساباً) لتحصل على مفتاحك.

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

يتأكد أن الـ API يعمل ويعيد صاحب المفتاح وحد الحسابات المرتبطة في باقته.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
curl -s "https://api.eaglebot99.com?resource=status" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "message": "API is working.",
    "user": {
        "id": 123,
        "name": "User Name",
        "email": "[email protected]"
    },
    "limits": {
        "max_linked_accounts": 10
    }
}
GET 2) قائمة الحسابات المرتبطة resource=accounts&action=list

كل حسابات سيرياتيل كاش وشام كاش المفعّلة والمرتبطة بصاحب المفتاح ضمن حدود باقته، بالحقول الأساسية فقط.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
curl -s "https://api.eaglebot99.com?resource=accounts&action=list" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=accounts&action=list');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "syriatel": [
            {
                "gsm": "0933xxxxxx",
                "cash_code": "123456"
            }
        ],
        "shamcash": [
            {
                "account_address": "251a***********************e"
            }
        ]
    }
}
GET 3) رصيد سيرياتيل كاش resource=syriatel&action=balance

رصيد حساب سيرياتيل كاش مرتبط ومفعّل (نصاً). gsm هو الرقم أو كود الكاش.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
gsm الرابط مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
curl -s "https://api.eaglebot99.com?resource=syriatel&action=balance&gsm=0933xxxxxx" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=balance&gsm=0933xxxxxx');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "gsm": "0933xxxxxx",
        "cash_code": "123456",
        "balance": "150000"
    }
}
GET 4) سجل سيرياتيل كاش الوارد resource=syriatel&action=history

العمليات الواردة إلى الحساب خلال الفترة، تُقرأ مباشرة من سيرياتيل وتُحفظ في الأرشيف. الحد الأقصى لعدد الصفحات المقروءة في الطلب الواحد: 10 (و20 لـ all)؛ في فترة مزدحمة جداً لا تظهر الأسطر الأقدم من ذلك.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
gsm الرابط مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
period الرابط اختياري الفترة: 7 أو 30 (يوماً) أو all — الافتراضي 7.
curl -s "https://api.eaglebot99.com?resource=syriatel&action=history&gsm=0933xxxxxx&period=7" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=history&gsm=0933xxxxxx&period=7');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "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"
            }
        ]
    }
}
GET 5) سجل سيرياتيل كاش الصادر resource=syriatel&action=outgoing_history

مثل السجل الوارد لكن للعمليات الصادرة من الحساب، مع "history_type": "outgoing".

أسماء بديلة: action=history_outgoing · action=sent_history

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
gsm الرابط مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
period الرابط اختياري الفترة: 7 أو 30 (يوماً) أو all — الافتراضي 7.
curl -s "https://api.eaglebot99.com?resource=syriatel&action=outgoing_history&gsm=0933xxxxxx&period=7" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=outgoing_history&gsm=0933xxxxxx&period=7');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "gsm": "0933xxxxxx",
        "cash_code": "123456",
        "period": "7",
        "history_type": "outgoing",
        "items": [
            {
                "transaction_no": "123456789",
                "date": "2025-01-01 11:20:00",
                "from": "0933xxxxxx",
                "to": "0944yyyyyy",
                "amount": "25000"
            }
        ]
    }
}
GET 6) البحث عن عملية سيرياتيل كاش resource=syriatel&action=find_tx

يبحث عن عملية واردة إلى حساب واحد خلال الفترة برقمها: في الأرشيف أولاً (دون العمليات الصادرة من الحساب نفسه، ودون ما سبق بداية الفترة) ثم في السجل الوارد مباشرة. إن توقفت القراءة عند حد الصفحات (10، و20 لـ all) قبل بداية الفترة فالرد 502 (بحث غير مكتمل) لا found:false.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
tx الرابط مطلوب رقم العملية كما يظهر في التطبيق (أرقام فقط، من 3 إلى 30).
gsm الرابط مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
period الرابط اختياري الفترة: 7 أو 30 (يوماً) أو all — الافتراضي 7.
curl -s "https://api.eaglebot99.com?resource=syriatel&action=find_tx&tx=123456789&gsm=0933xxxxxx&period=7" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=find_tx&tx=123456789&gsm=0933xxxxxx&period=7');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "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"
        }
    }
}
POST 7) تحويل سيرياتيل كاش resource=syriatel&action=transfer_cash

يحوّل من حساب مرتبط إلى رقم مستفيد (أو كود كاش). الرقم يجب أن يكون هو المستفيد الذي تجده سيرياتيل وإلا لا يُرسل شيء (400). تحويل واحد في الوقت نفسه لكل حساب؛ وكل رد على التحويل ليس نجاحاً ولا رفضاً صريحاً من سيرياتيل يجعل نتيجته غير معروفة، فلا يُعاد إرساله أبداً (502): تحقّق من السجل الصادر أولاً.

عملية مالية: POST فقط، والمعاملات في جسم الطلب فقط (x-www-form-urlencoded أو multipart أو JSON) — أي معامل منها في الرابط يُرفض (400). أرسل ترويسة Idempotency-Key لتجنّب التنفيذ المزدوج.
المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
gsm جسم الطلب مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
to_gsm جسم الطلب مطلوب رقم المستفيد (أو كود الكاش الخاص به).
amount جسم الطلب مطلوب المبلغ: رقم موجب.
pin_code جسم الطلب مطلوب الرمز السري (PIN) لسيرياتيل كاش: 4 أرقام. لا يُحفظ ولا يُسجَّل.
# A NEW Idempotency-Key for every transfer; send the same one again only to retry THAT transfer.
IDEMPOTENCY_KEY="$(openssl rand -hex 16)"
curl -s -X POST "https://api.eaglebot99.com?resource=syriatel&action=transfer_cash" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-urlencode "gsm=0933xxxxxx" \
  --data-urlencode "to_gsm=0995xxxxxxx" \
  --data-urlencode "amount=100" \
  --data-urlencode "pin_code=1234"
<?php
// A NEW Idempotency-Key for every transfer (keep it with your order): send the same one
// again only to retry THAT transfer. Reused for another transfer, it returns the first
// transfer's stored answer and sends nothing.
$idempotencyKey = bin2hex(random_bytes(16));

$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=transfer_cash');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json', 'Idempotency-Key: '.$idempotencyKey],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'gsm' => '0933xxxxxx',
        'to_gsm' => '0995xxxxxxx',
        'amount' => '100',
        'pin_code' => '1234',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "source_account": {
            "gsm": "0933xxxxxx",
            "cash_code": "123456"
        },
        "beneficiary": {
            "gsm": "0995xxxxxxx"
        },
        "amount": "100",
        "fee": "5",
        "billcode": "ABCDEF123",
        "message": "تم التحويل بنجاح"
    }
}
POST 8) شحن رصيد موبايل سيرياتيل resource=syriatel&action=mobile_recharge

يتحقق من الطلب (الحساب، الرقم، الفئة، الرمز) ثم يعيد 501: الشحن غير مدعوم حالياً على هذه المنصة ولا يُرسل شيء إلى سيرياتيل.

عملية مالية: POST فقط، والمعاملات في جسم الطلب فقط (x-www-form-urlencoded أو multipart أو JSON) — أي معامل منها في الرابط يُرفض (400). أرسل ترويسة Idempotency-Key لتجنّب التنفيذ المزدوج.
المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
gsm جسم الطلب مطلوب رقم حساب سيرياتيل كاش المرتبط (09… أو 9639… أو +9639…) أو كود الكاش الخاص به.
target_gsm جسم الطلب مطلوب الرقم المراد شحنه.
category جسم الطلب مطلوب فئة الشحن: إحدى القيم الثابتة (مثل 1.92 أو 125 أو 1250).
pin_code جسم الطلب مطلوب الرمز السري (PIN) لسيرياتيل كاش: 4 أرقام. لا يُحفظ ولا يُسجَّل.
# A NEW Idempotency-Key for every transfer; send the same one again only to retry THAT transfer.
IDEMPOTENCY_KEY="$(openssl rand -hex 16)"
curl -s -X POST "https://api.eaglebot99.com?resource=syriatel&action=mobile_recharge" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-urlencode "gsm=0933xxxxxx" \
  --data-urlencode "target_gsm=0998xxxxxxx" \
  --data-urlencode "category=1.92" \
  --data-urlencode "pin_code=1234"
<?php
// A NEW Idempotency-Key for every transfer (keep it with your order): send the same one
// again only to retry THAT transfer. Reused for another transfer, it returns the first
// transfer's stored answer and sends nothing.
$idempotencyKey = bin2hex(random_bytes(16));

$ch = curl_init('https://api.eaglebot99.com?resource=syriatel&action=mobile_recharge');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json', 'Idempotency-Key: '.$idempotencyKey],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'gsm' => '0933xxxxxx',
        'target_gsm' => '0998xxxxxxx',
        'category' => '1.92',
        'pin_code' => '1234',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": false,
    "error": "شحن رصيد الموبايل غير مدعوم حالياً على هذه المنصة."
}
GET 9) رصيد شام كاش resource=shamcash&action=balance

أرصدة كل العملات (USD و SYP و EUR) لحساب شام كاش مرتبط، كأرقام.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
account_address الرابط مطلوب عنوان حساب شام كاش المرتبط (المصدر).
curl -s "https://api.eaglebot99.com?resource=shamcash&action=balance&account_address=251awSOURCE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=shamcash&action=balance&account_address=251awSOURCE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "account_address": "251aw******************",
        "balances": [
            {
                "currency": "USD",
                "balance": 0
            },
            {
                "currency": "SYP",
                "balance": 20980
            },
            {
                "currency": "EUR",
                "balance": 0
            }
        ]
    }
}
GET 10) سجل شام كاش الوارد resource=shamcash&action=logs

التحويلات الواردة إلى حساب شام كاش مرتبط: تُقرأ أحدث صفحة مباشرة ثم يُعاد كل ما في الأرشيف، الأحدث أولاً.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
account_address الرابط مطلوب عنوان حساب شام كاش المرتبط (المصدر).
limit الرابط اختياري عدد العمليات في الرد: من 1 إلى 500 (الافتراضي 100).
curl -s "https://api.eaglebot99.com?resource=shamcash&action=logs&account_address=251awSOURCE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=shamcash&action=logs&account_address=251awSOURCE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "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": "شحن رصيد"
            }
        ]
    }
}
GET 11) سجل شام كاش الصادر resource=shamcash&action=outgoing_logs

مثل السجل الوارد لكن للتحويلات الصادرة من الحساب، مع "log_type": "outgoing".

أسماء بديلة: action=logs_outgoing · action=sent_logs

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
account_address الرابط مطلوب عنوان حساب شام كاش المرتبط (المصدر).
limit الرابط اختياري عدد العمليات في الرد: من 1 إلى 500 (الافتراضي 100).
curl -s "https://api.eaglebot99.com?resource=shamcash&action=outgoing_logs&account_address=251awSOURCE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=shamcash&action=outgoing_logs&account_address=251awSOURCE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "account_address": "251aw******************",
        "log_type": "outgoing",
        "items": [
            {
                "tran_id": "987654321",
                "from_name": "Your Name",
                "to_name": "Client Name",
                "currency": "SYP",
                "amount": 25000,
                "datetime": "2025-01-01 10:15:00",
                "account": "251aw******************",
                "note": "تحويل رصيد"
            }
        ]
    }
}
GET 12) البحث عن عملية شام كاش resource=shamcash&action=find_tx

يبحث عن عملية واردة إلى حساب شام كاش مرتبط برقمها: في الأرشيف أولاً ثم في السجل مباشرة. التحويل الذي أرسله الحساب نفسه لا يُعدّ (found:false)، فلا يمر رقم دفعة صادرة على أنه دفعة واردة.

المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
tx الرابط مطلوب رقم العملية كما يظهر في التطبيق (أرقام فقط، من 3 إلى 30).
account_address الرابط مطلوب عنوان حساب شام كاش المرتبط (المصدر).
curl -s "https://api.eaglebot99.com?resource=shamcash&action=find_tx&tx=123456789&account_address=251awSOURCE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
<?php
$ch = curl_init('https://api.eaglebot99.com?resource=shamcash&action=find_tx&tx=123456789&account_address=251awSOURCE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "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******************"
        }
    }
}
POST 13) تحويل شام كاش resource=shamcash&action=transfer

يحوّل من حساب شام كاش مرتبط ومفعّل إلى حساب شام كاش آخر، بعد انقضاء مهلة الربط بالمنصة (24 ساعة). الملاحظة حتى 50 حرفاً.

عملية مالية: POST فقط، والمعاملات في جسم الطلب فقط (x-www-form-urlencoded أو multipart أو JSON) — أي معامل منها في الرابط يُرفض (400). أرسل ترويسة Idempotency-Key لتجنّب التنفيذ المزدوج.
المعاملات
المعاملالمكانالوصف
api_key الترويسة أو الرابط مطلوب مفتاح الـ API: في الترويسة X-Api-Key (المفضّل)، أو ?api_key= في الرابط، أو Authorization: Bearer، أو الحقل api_key في جسم طلب POST.
account_address جسم الطلب مطلوب عنوان حساب شام كاش المرتبط (المصدر).
receive_key جسم الطلب مطلوب عنوان حساب شام كاش المستلم.
amount جسم الطلب مطلوب المبلغ: رقم موجب.
currency جسم الطلب مطلوب العملة: USD أو SYP (EUR للقراءة فقط).
note جسم الطلب اختياري ملاحظة اختيارية، حتى 50 حرفاً.
confirm_code جسم الطلب اختياري رمز التأكيد المالي، فقط إن كان شام كاش يطلبه لهذا المبلغ. لا يُحفظ.
# A NEW Idempotency-Key for every transfer; send the same one again only to retry THAT transfer.
IDEMPOTENCY_KEY="$(openssl rand -hex 16)"
curl -s -X POST "https://api.eaglebot99.com?resource=shamcash&action=transfer" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-urlencode "account_address=251awSOURCE" \
  --data-urlencode "receive_key=251awRECEIVER" \
  --data-urlencode "amount=100" \
  --data-urlencode "currency=USD" \
  --data-urlencode "note=API transfer test"
<?php
// A NEW Idempotency-Key for every transfer (keep it with your order): send the same one
// again only to retry THAT transfer. Reused for another transfer, it returns the first
// transfer's stored answer and sends nothing.
$idempotencyKey = bin2hex(random_bytes(16));

$ch = curl_init('https://api.eaglebot99.com?resource=shamcash&action=transfer');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Accept: application/json', 'Idempotency-Key: '.$idempotencyKey],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'account_address' => '251awSOURCE',
        'receive_key' => '251awRECEIVER',
        'amount' => '100',
        'currency' => 'USD',
        'note' => 'API transfer test',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($response['success'] ?? false) {
    print_r($response);
} else {
    echo $status, ': ', $response['error'] ?? 'unknown error';
}
{
    "success": true,
    "data": {
        "message": "تم تحويل مبلغ 5 USD بنجاح ✅",
        "source_account": {
            "account_address": "251awSOURCE***********"
        },
        "recipient": {
            "address": "251awRECEIVER*********",
            "userName": "Client Name"
        },
        "transfer": {
            "amount": "5",
            "currency": "USD",
            "note": "API transfer test"
        }
    }
}
تجنّب التنفيذ المزدوج (Idempotency-Key)

مع كل طلب مالي (POST) يمكنك إرسال ترويسة Idempotency-Key بقيمة فريدة من عندك لكل تحويل (أو الحقل request_id في الجسم: نص أو عدد صحيح؛ أي نوع آخر يُرفض بـ 400، ولا يُقبل في الرابط). لا تُعِد استخدامها لتحويل آخر: سيُعاد رد التحويل الأول ولن يُرسل شيء.

  • المفتاح نفسه بالمعاملات نفسها: يُعاد الرد المحفوظ كما هو ولا يُرسل شيء مرة ثانية (مع الترويسة Idempotent-Replayed: true).
  • المفتاح نفسه بمعاملات مختلفة: 422.
  • المفتاح نفسه والطلب الأول ما زال قيد التنفيذ: 409. وإن بقي دون نتيجة أكثر من 10 دقائق: 502 (النتيجة غير معروفة) ولا يُنفَّذ أبداً مرة ثانية.
  • لا يُحرَّر المفتاح (فيمكن استخدامه مرة أخرى) إلا حين يكون مؤكداً أن شيئاً لم ينتقل: رفض قبل إرسال أي شيء (معامل خاطئ، الحساب مشغول بتحويل آخر…)، أو رفض صريح من سيرياتيل للتحويل برمزها (الرصيد، الرمز السري…). وكل رد آخر يبقى مرتبطاً بالمفتاح ويُعاد كما هو: النجاح، ورفض شام كاش لتحويل أُرسل (400)، والنتيجة غير المعروفة (502).
  • تُحفظ المفاتيح التي عُرف ردها (أي رد أقل من 500: نجاح أو رفض) 30 يوماً من إنشائها ثم تُحذف: بعدها يُنفَّذ طلب بالمفتاح نفسه كطلب جديد، فلا تُعِد محاولة تحويل قديم بمفتاحه. أما المفتاح الذي بقي قيد التنفيذ أو كان رده 5xx (نتيجة غير معروفة) فيُحفظ دائماً ولا يُنفَّذ بمفتاحه مرة ثانية أبداً.
الحدود
  • الحد الافتراضي للطلبات في الدقيقة لكل مفتاح: 60، وقد تحدد باقة الاشتراك أو إعدادات الحساب حداً آخر (حدّك أنت يظهر هنا بعد تسجيل الدخول وفي صفحة إعدادات الـ API)؛ وبعده 429 مع retry_after والترويسة Retry-After.
  • أكثر من 30 محاولةً بمفتاح مفقود أو خاطئ من العنوان نفسه في الدقيقة: 429.
  • يمكنك قصر مفتاحك على عناوين IP محددة من صفحة الإعدادات.
  • مهلة تحويلات شام كاش بعد ربط الحساب بالمنصة: 24 ساعة.
  • الحد الأقصى لعدد صفحات سجل سيرياتيل كاش المقروءة مباشرة في الطلب الواحد: 10 (و20 لـ period=all)؛ في فترة مزدحمة جداً لا يعيد history الأسطر الأقدم من ذلك، ويجيب find_tx بـ 502 (بحث غير مكتمل) لا بـ found:false إن توقف عند هذا الحد قبل بداية الفترة.
  • معاملات الطلبات المالية في جسم الطلب فقط: gsm, to_gsm, amount, pin_code, target_gsm, category, account_address, receive_key, currency, note, confirm_code, request_id
HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
    "success": false,
    "error": "تم تجاوز الحد المسموح للطلبات. حاول مرة أخرى بعد قليل.",
    "retry_after": 30
}
رموز الأخطاء

صيغة الخطأ دائماً:

{
    "success": false,
    "error": "Missing API key. استخدم X-Api-Key أو ?api_key="
}
HTTPالمعنى
200نجاح.
400طلب ناقص أو معامل غير صالح (مثلاً لا gsm أو account_address)، أو رفض مزوّد الخدمة العملية.
401المفتاح مفقود أو غير صحيح.
403غير مسموح: المفتاح موقوف، الحساب غير مفعّل أو خارج الباقة، الاشتراك لا يشمل الـ API، عنوان IP غير مسموح، أو نقطة النهاية موقوفة.
404نقطة نهاية غير معروفة، أو حساب غير مرتبط بهذا المستخدم.
405طريقة HTTP غير مدعومة (القراءة GET والعمليات المالية POST).
409طلب بمفتاح Idempotency-Key نفسه قيد التنفيذ.
422مفتاح Idempotency-Key استُخدم لطلب مختلف.
429تجاوز حد الطلبات، أو تحويل آخر من الحساب قيد التنفيذ.
500خطأ داخلي في الخادم.
501العملية غير مدعومة على هذه المنصة (شحن الموبايل).
502خطأ من مزوّد الخدمة (سيرياتيل / شام كاش)، أو نتيجة تحويل غير معروفة، أو بحث find_tx لم يكتمل.