GET/api/v2/account/wallet/transactions
حركات المحفظة
سجل مدين ودائن مع الرصيد بعد كل حركة، ومنح الرسائل المجانية. لا تُعاد وسائل دفع أو أسرار.
متى تستخدمه. مطابقة استهلاك الإرسال مع الفوترة في نظامك.
مثال الطلب
مثال صحيح: آخر الحركات
curl --location 'https://raselsms.com/api/v2/account/wallet/transactions' \--header 'X-API-Key: YOUR_API_KEY'مثال الاستجابة
200 — آخر الحركات
{ "success": true, "data": { "transactions": [ { "id": "6800bbb123def4567890aaaa", "amount": 0.12, "type": "debit", "source": "usage", "description": "SMS send", "balanceAfter": 4.88, "messageCount": 1, "createdAt": "2026-07-20T14:22:00.000Z" } ], "total": 1, "balance": 4.88, "skip": 0, "limit": 100 }}401 — مفتاح API مفقود أو غير صالح.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — الهاتف غير موثّق أو الصلاحية غير كافية (غالباً messages:create أو api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}طلب HTTP
GET /api/v2/account/wallet/transactions
ترويسات الطلب
| الترويسة | النوع | الوصف |
|---|---|---|
| X-API-Key | string | مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. * |
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
| skip | integer | عدد الصفوف المراد تخطيها. الافتراضي 0. |
| limit | integer | حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب. |
| fromDate | string | تاريخ البداية ضمن النطاق (YYYY-MM-DD). |
| toDate | string | تاريخ النهاية ضمن النطاق (YYYY-MM-DD). |
| type | credit | debit | قيمة الفلتر. في المحادثات: all أو direct أو group. في حركات المحفظة: credit أو debit. |
| source | admin_topup | usage | topup_request | default_plan_bonus | trial_balance | admin_withdrawal | subscription_refund | subscription_payment | coupon | send_failure_refund | مصدر حركة المحفظة مثل usage أو admin_topup أو topup_request. في رفع الوسائط هو أصل الأصل المخزّن. |
حقول الاستجابة
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| success | boolean | صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. | |
| data | object | البيانات الأساسية في مسارات القوائم وملخص الحساب. | |
| data.transactions | json | صفوف مدين ودائن للمحفظة. | |
| data.freeMessageGrants | object | منح الرسائل المجانية من الإدارة. | |
| data.freeMessageGrants.summary | object | مجاميع منح الرسائل المجانية على هذا الحساب. | |
| data.freeMessageGrants.summary.totals | object | الرسائل الممنوحة والمستهلكة والمحجوزة والمسحوبة والمتبقية. | |
| data.freeMessageGrants.summary.totals.granted | number | الرسائل المجانية التي مُنحت. | |
| data.freeMessageGrants.summary.totals.consumed | number | الرسائل المجانية التي استُخدمت. | |
| data.freeMessageGrants.summary.totals.reserved | number | الرسائل المجانية المحجوزة لإرسال لم يكتمل. | |
| data.freeMessageGrants.summary.totals.withdrawn | number | الرسائل المجانية التي سحبها المشرف. | |
| data.freeMessageGrants.summary.totals.remaining | number | الرسائل المجانية التي لم تُستخدم بعد. | |
| data.freeMessageGrants.summary.totals.activeRemaining | number | المتبقي في المنح التي ما زالت سارية. | |
| data.freeMessageGrants.summary.activeGrantCount | integer | عدد المنح التي ما زالت سارية. | |
| data.freeMessageGrants.summary.grantCount | integer | عدد المنح كله، بما فيها غير السارية. | |
| data.freeMessageGrants.summary.byScope | json | الرسائل المجانية المتبقية مجمّعة حسب القناة أو النطاق. | |
| data.freeMessageGrants.grants | json | منح الرسائل المجانية كل واحدة على حدة. | |
| data.total | integer | إجمالي الصفوف المطابقة. | |
| data.balance | number | رصيد المحفظة بعد آخر حركة، أو الرصيد الظاهر الآن. | |
| data.skip | integer | عدد الصفوف المراد تخطيها. الافتراضي 0. | |
| data.limit | integer | حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب. |
رموز الحالة
| الحالة | الوصف |
|---|---|
| 200 | نجاح. |
| 401 | مفتاح API مفقود أو غير صالح. |
| 403 | الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء. |
| 429 | تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى. |
جرّب الطلب
المتغيرات
عدد الصفوف المراد تخطيها. الافتراضي 0.
حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب.
تاريخ البداية ضمن النطاق (YYYY-MM-DD).
تاريخ النهاية ضمن النطاق (YYYY-MM-DD).
قيمة الفلتر. في المحادثات: all أو direct أو group. في حركات المحفظة: credit أو debit.
مصدر حركة المحفظة مثل usage أو admin_topup أو topup_request. في رفع الوسائط هو أصل الأصل المخزّن.
الطلب
GET /api/v2/account/wallet/transactions?skip=0&limit=100&fromDate=2026-01-01&toDate=2026-06-30&type=debit&source=usageالاستجابة
نفّذ طلباً لعرض الاستجابة.