الفوترة

فوترة Ithbat تُدار من لوحة تحكم المسؤول ومن الـ Billing API. المدفوعات تمر عبر Stripe للبطاقات الدولية وMoyasar لمدفوعات منطقة الشرق الأوسط بما فيها مدى (السعودية). العملات المدعومة: USD و SAR و EGP.

خطط الاشتراك

الخطة	مناسبة لـ
Starter	فرق صغيرة وتطبيقات في بداياتها. المصادقة الأساسية، حتى 1,000 MAU
Growth	تطبيقات في نمو. SAML SSO و SCIM و إخطارات آلية ونطاقات مخصصة، حتى 10,000 MAU
Enterprise	مؤسسات كبيرة. قاعدة بيانات مخصصة و Data Residency و SLA، مستخدمون بلا حد، عقود مخصصة

حدود الخطط ومجموعات الميزات معرّفة في المنصة ويمكنك تجلبها عبر:

GET /api/v1/billing/plans
Authorization: Bearer {token}

عرض الاشتراك الحالي

GET /api/v1/billing/subscription
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

الـ Response:

{
  "id": "sub_abc123",
  "planId": "growth",
  "planName": "Growth",
  "status": "active",
  "currentPeriodStart": "2026-02-01T00:00:00Z",
  "currentPeriodEnd": "2026-03-01T00:00:00Z",
  "currency": "usd",
  "amount": 9900,
  "interval": "month",
  "cancelAtPeriodEnd": false,
  "paymentProvider": "stripe",
  "createdAt": "2025-06-01T10:00:00Z"
}

إنشاء اشتراك

الخطوة 1 -- جلب الخطط المتاحة

GET /api/v1/billing/plans
Authorization: Bearer {token}

الخطوة 2 -- تقدير التكلفة

POST /api/v1/billing/estimates
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "planId": "growth",
  "currency": "sar",
  "interval": "year"
}

الـ Response:

{
  "planId": "growth",
  "currency": "sar",
  "interval": "year",
  "amount": 26400,
  "formattedAmount": "SAR 264.00",
  "discount": {
    "percentage": 20,
    "description": "Annual discount"
  }
}

الخطوة 3 -- إنشاء Payment Intent

POST /api/v1/payments/intent
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "planId": "growth",
  "currency": "sar",
  "interval": "month",
  "paymentMethodId": "pm_abc123"
}

الخطوة 4 -- تأكيد الدفع

POST /api/v1/payments/confirm
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "paymentIntentId": "pi_abc123"
}

بعد التأكيد، الاشتراك يتفعّل فورًا.

وسائل الدفع

الخيارات المدعومة

المزود	الوسائل	العملات
Stripe	Visa، Mastercard، Amex، Apple Pay، Google Pay	USD، EUR، GBP
Moyasar	مدى، Visa، Mastercard، STC Pay	SAR
Moyasar	Visa، Mastercard، Fawry	EGP

التحويل البنكي متاح لخطط Enterprise السنوية. تواصل مع [email protected].

إضافة وسيلة دفع

POST /api/v1/billing/payment-methods
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "provider": "stripe",
  "token": "tok_visa_from_stripe_elements"
}

لمدفوعات Moyasar، الـ token هو source_id الذي يرجع من Moyasar.js SDK.

جلب وسائل الدفع

GET /api/v1/billing/payment-methods
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

تعيين الوسيلة الافتراضية

PUT /api/v1/billing/payment-methods/{id}/default
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

إزالة وسيلة دفع

DELETE /api/v1/billing/payment-methods/{id}
Authorization: Bearer {token}

دعم العملات المتعددة

Ithbat يصدر الفواتير بالعملة المناسبة لمنطقتك.

العملة	المنطقة	الرمز
USD	عالمي	$
SAR	السعودية	ر.س
EGP	مصر	ج.م

العملة تتحدد وقت إنشاء الاشتراك. إذا أردت تغيّرها: لخطط Enterprise تواصل مع الدعم، لخطط Growth ألغِ الاشتراك وأعد إنشاءه.

كل المبالغ في الـ API بـأصغر وحدة للعملة (سنتات لـ USD، هللات لـ SAR، قروش لـ EGP). اقسم على 100 لكي تحصل على المبلغ الفعلي.

تغيير الاشتراك

ترقية أو تخفيض في أي وقت:

PUT /api/v1/billing/subscription
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "planId": "enterprise",
  "interval": "year"
}

الترقيات تسري فورًا. التخفيضات تسري نهاية فترة الفوترة الحالية. Proration يتحسب تلقائيًا عبر Stripe/Moyasar.

إلغاء الاشتراك

POST /api/v1/billing/subscription/cancel
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

الافتراضي: الإلغاء يسري نهاية فترة الفوترة الحالية (cancelAtPeriodEnd: true). حسابك يبقى نشط لحد ذاك الوقت. بعد الإلغاء، المستفيد ينزل لخطة Starter.

الفواتير والإيصالات

جلب كل الفواتير

GET /api/v1/billing/invoices
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

الـ Response يتضمن قائمة فواتير مع id وamount وcurrency وstatus وcreatedAt.

جلب فاتورة محددة

GET /api/v1/billing/invoices/{id}
Authorization: Bearer {token}

تنزيل فاتورة PDF

GET /api/v1/billing/invoices/{id}/pdf
Authorization: Bearer {token}

يرجع ملف PDF جاهز للمحاسبة والضرائب. الفواتير تتضمن اسم الشركة والعنوان (من إعدادات الفوترة) والرقم الضريبي (إذا موجود) وبنود الفاتورة.

الفوترة القائمة على الاستخدام

الاستخدام يُتتبع شهريًا ويظهر في لوحة الفوترة.

المقاييس المتتبعة

المقياس	الوصف
MAU (المستخدمون النشطون شهريًا)	المستخدمون الذين سجّلوا دخول مرة على الأقل بالشهر
API Calls	إجمالي الـ API Requests المصادَقة بالشهر
SCIM Syncs	عدد عمليات SCIM Provisioning
إخطار آلي Deliveries	إجمالي محاولات تسليم إخطار آلي

جلب الاستخدام الحالي

GET /api/v1/billing/usage
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

{
  "period": "2026-02",
  "mau": 1247,
  "mauLimit": 10000,
  "apiCalls": 183400,
  "scimSyncs": 3200,
  "webhookDeliveries": 9100
}

جلب ملخص استخدام المستفيد

GET /api/v1/tenant/usage
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

جلب حدود الخطة

GET /api/v1/tenant/limits
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

إعدادات الفوترة

عيّن اسم الشركة والرقم الضريبي وعنوان الفوترة لكي تظهر في الفواتير:

PATCH /api/v1/tenant/settings/general
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "billingName": "Acme Corp Ltd",
  "billingEmail": "[email protected]",
  "billingAddress": {
    "line1": "King Fahd Road",
    "city": "Riyadh",
    "country": "SA",
    "postalCode": "12345"
  },
  "vatNumber": "SA300000000000003"
}

Billing API Reference

Method	Endpoint	الصلاحية
`GET`	`/api/v1/billing/plans`	`billing:read`
`GET`	`/api/v1/billing/subscription`	`billing:read`
`GET`	`/api/v1/billing/invoices`	`billing:read`
`GET`	`/api/v1/billing/invoices/{id}`	`billing:read`
`GET`	`/api/v1/billing/invoices/{id}/pdf`	`billing:read`
`GET`	`/api/v1/billing/usage`	`billing:read`
`GET`	`/api/v1/billing/payment-methods`	`billing:read`
`POST`	`/api/v1/billing/subscription`	`billing:write`
`PUT`	`/api/v1/billing/subscription`	`billing:write`
`POST`	`/api/v1/billing/subscription/cancel`	`billing:write`
`POST`	`/api/v1/billing/estimates`	`billing:write`
`POST`	`/api/v1/billing/payment-methods`	`billing:write`
`DELETE`	`/api/v1/billing/payment-methods/{id}`	`billing:write`
`PUT`	`/api/v1/billing/payment-methods/{id}/default`	`billing:write`
`POST`	`/api/v1/payments/intent`	`billing:write`
`POST`	`/api/v1/payments/confirm`	`billing:write`

المشتريات المؤسسية

لخطط Enterprise بأسعار مخصصة و SLA واتفاقيات معالجة بيانات (DPA) أو أوامر شراء:

أرسل بريد لـ [email protected]
وضّح العدد المتوقع من MAU والمناطق المطلوبة ومتطلبات الامتثال (PDPL أو GDPR وغيرها)

العقود المؤسسية تدعم الفوترة السنوية بالـ SAR أو USD أو EGP ومتاحة بعقود 12 شهر و 24 شهر.

الخطوات التالية

Multi-Tenancy ← فهم حدود الخطة لكل مستفيد
سجل التدقيق ← أحداث تغيير الاشتراك تتسجّل في Audit Log
RBAC والصلاحيات ← تحكّم بمن يملك صلاحية billing:read و billing:write

خطط الاشتراك​

عرض الاشتراك الحالي​

إنشاء اشتراك​

الخطوة 1 -- جلب الخطط المتاحة​

الخطوة 2 -- تقدير التكلفة​

الخطوة 3 -- إنشاء Payment Intent​

الخطوة 4 -- تأكيد الدفع​

وسائل الدفع​

الخيارات المدعومة​

إضافة وسيلة دفع​

جلب وسائل الدفع​

تعيين الوسيلة الافتراضية​

إزالة وسيلة دفع​

دعم العملات المتعددة​

تغيير الاشتراك​

إلغاء الاشتراك​

الفواتير والإيصالات​

جلب كل الفواتير​

جلب فاتورة محددة​

تنزيل فاتورة PDF​

الفوترة القائمة على الاستخدام​

المقاييس المتتبعة​

جلب الاستخدام الحالي​

جلب ملخص استخدام المستفيد​

جلب حدود الخطة​

إعدادات الفوترة​

Billing API Reference​

المشتريات المؤسسية​

الخطوات التالية​