GET/api/v2/account/subscriptions
سجل الاشتراكات
فترات الاشتراك والرسوم مع ترقيم الصفحات، بالإضافة إلى freeMessageGrants. الحقول الداخلية الحساسة محذوفة.
متى تستخدمه. عرض تاريخ الفوترة أو حالة الخطة في نظام خارجي.
مثال الطلب
مثال صحيح: أول صفحة
curl --location 'https://raselsms.com/api/v2/account/subscriptions' \--header 'X-API-Key: YOUR_API_KEY'مثال الاستجابة
200 — أول صفحة
{ "success": true, "data": { "subscriptions": [ { "id": "6800sub123def4567890aaaa", "planName": "Growth", "status": "active", "startAt": "2026-07-01T00:00:00.000Z", "endAt": "2026-08-01T00:00:00.000Z", "isTrial": false } ], "total": 1, "skip": 0, "limit": 20, "freeMessageGrants": { "summary": { "totals": { "granted": 100, "consumed": 10, "reserved": 0, "withdrawn": 0, "remaining": 90, "activeRemaining": 90 }, "activeGrantCount": 1, "grantCount": 1, "byScope": [ { "channel": "sms_local", "providerKey": null, "messageType": "all", "remaining": 90, "grantCount": 1 } ] }, "grants": [ { "id": "6800abc123def4567890fedc", "channel": "sms_local", "remainingQuantity": 90, "status": "active", "reason": "admin_gift" } ] } }}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/subscriptions
ترويسات الطلب
| الترويسة | النوع | الوصف |
|---|---|---|
| X-API-Key | string | مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. * |
معاملات الاستعلام
| الحقل | النوع | الوصف |
|---|---|---|
| skip | integer | عدد الصفوف المراد تخطيها. الافتراضي 0. |
| limit | integer | حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب. |
| status | pending | active | scheduled | expired | paused | cancelled | upgrade_pending | حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. |
| include | charges | subscriptions | الافتراضي يشمل الاشتراكات والرسوم معاً. استخدم subscriptions لإخفاء الرسوم. |
حقول الاستجابة
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| success | boolean | صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. | |
| data | object | البيانات الأساسية في مسارات القوائم وملخص الحساب. | |
| data.subscriptions | json | فترات الاشتراك المرقّمة. | |
| data.charges | 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.totalSubscriptions | integer | عدد فترات الاشتراك المطابقة للتصفية. | |
| data.totalCharges | integer | عدد حركات الخصم المطابقة للتصفية. | |
| data.skip | integer | عدد الصفوف المراد تخطيها. الافتراضي 0. | |
| data.limit | integer | حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب. |
رموز الحالة
| الحالة | الوصف |
|---|---|
| 200 | نجاح. |
| 401 | مفتاح API مفقود أو غير صالح. |
| 403 | الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء. |
| 429 | تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى. |
جرّب الطلب
المتغيرات
عدد الصفوف المراد تخطيها. الافتراضي 0.
حجم الصفحة. عادة 1–50 لسياق المحادثة و1–500 لقوائم الحساب.
حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها.
الافتراضي يشمل الاشتراكات والرسوم معاً. استخدم subscriptions لإخفاء الرسوم.
الطلب
GET /api/v2/account/subscriptions?status=pending&include=chargesالاستجابة
نفّذ طلباً لعرض الاستجابة.