> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# الفوترة

> كيف تعمل المحفظة والشحن وميزانيّات المشاريع والفواتير في بوّابة Wave.

لكلّ منظّمة **محفظة** واحدة في Wave. تُخصم الرسوم من المحفظة. تدير المحفظة من صفحة
**الفوترة** في البوّابة. كلّ المبالغ بالريال السعودي (SAR).

## من يستطيع فعل ماذا

| الدور | ما يستطيع الدور فعله في صفحة الفوترة |
| - | - |
| `owner` | كلّ شيء: القراءة، والشحن، وتقسيم المحفظة بين المشاريع، وتشغيل ميزانيّات المشاريع أو إيقافها، وإنشاء فاتورة. |
| `billing` | القراءة، والشحن، وتقسيم المحفظة بين المشاريع. |
| `admin` | القراءة، وإنشاء فاتورة. لا يستطيع `admin` شحن المحفظة أو تقسيمها. |
| `developer` و`supervisor` و`agent` | لا وصول إلى صفحة الفوترة. |

صفحة الفوترة مفتوحة من اليوم الأوّل. لا تحتاج إلى Go-Live لاستخدامها.

## المحفظة

يعرض أعلى صفحة الفوترة **رصيدك**. وتحته الأجزاء التالية:

* **خطة الأسعار.** سعر الوحدة لكلّ نوع استخدام.
* **الاستهلاك.** رسوم آخر 30 يومًا، مع السعر بالريال. تعرض القائمة 500 رسم كحدّ أقصى.
* **الفواتير.** فواتير منظّمتك.

عندما يكون الرصيد 0 أو أقلّ، يُعيد أيّ إجراء يكلّف مالًا الخطأ `402
INSUFFICIENT_CREDITS`. شراء رقم مثال على ذلك. اشحن المحفظة للمتابعة.

### رسوم المكالمات

يحتسب رسم المكالمة كلّ دقيقة بدأت من مكالمة production مُجابة. الحدّ الأدنى دقيقة
واحدة. لا تُفوتَر مكالمة الـ sandbox. راجع [وضع الـ Sandbox](https://docs.wave.sa/ar/sandbox-mode.md).
يظهر كلّ رسم في قائمة **الاستهلاك**، ويُخصم مبلغه من المحفظة.

## اشحن المحفظة

1. افتح **الفوترة**.
2. اختر مبلغًا (50 أو 100 أو 500 ريال)، أو اكتب مبلغك. يجب أن يكون المبلغ أكبر من 0
   وألّا يزيد على 100,000 ريال.
3. اختر **إعادة شحن**.
4. تنقلك البوّابة إلى صفحة الدفع الخاصّة بمزوّد الدفع. ادفع هناك ببطاقة أو بـ Apple
   Pay.

بعد الدفع تعرض البوّابة **تم استلام الدفعة** والرصيد الجديد. يُعلم مزوّد الدفع Wave
بأنّ الدفعة اكتملت، ثمّ تضيف Wave المال إلى المحفظة. إذا عرضت الصفحة **لم يتم تأكيد
الدفعة بعد**، انتظر قليلًا ثمّ اختر **تحقق مرة أخرى**. تضيف Wave المال مرّة واحدة
فقط، حتى إذا اخترت **تحقق مرة أخرى** مرّات كثيرة.

يستطيع الشحن `owner` ودور `billing` فقط. إذا لم يستطع مزوّد الدفع بدء الدفعة، تعرض
البوّابة خطأ (`502 PAYMENT_FAILED`). حاول مرّة أخرى لاحقًا.

## ميزانيّات المشاريع

افتراضيًّا تنفق كلّ المشاريع من الرصيد الرئيسي. مع **ميزانيات المشاريع** تعطي كلّ
مشروع جزءًا خاصًّا به من المحفظة. ولا يستطيع المشروع الإنفاق إلّا من ميزانيّته.

**ميزانيات المشاريع** مفتاح تشغيل للمنظّمة كلّها. يستطيع `owner` فقط تشغيله أو
إيقافه.

* **متوقّف (الافتراضي).** يُخصم كلّ رسم من الرصيد الرئيسي.
* **يعمل.** ينفق كلّ مشروع من ميزانيّته. وعندما تصل ميزانيّة المشروع إلى 0، يتوقّف
  المشروع مع `402 INSUFFICIENT_PROJECT_BALANCE`.

> [!WARNING]
>
> عندما تشغّل المفتاح، لا ينتقل أيّ مال. المشروع الذي لا ميزانيّة له يتوقّف عن العمل
> إلى أن تضيف إليه مالًا.

لنقل المال:

1. في **ميزانيات المشاريع** ابحث عن المشروع. **غير مخصص** هو جزء المحفظة
   الذي لا يملكه أيّ مشروع.
2. اكتب مبلغًا بالريال (خانتان عشريّتان كحدّ أقصى).
3. اختر **إضافة إلى المشروع** لنقل المال من المبلغ غير المخصّص إلى المشروع. واختر
   **استرجاع** لنقل المال من المشروع إلى المبلغ غير المخصّص.

إذا كان المبلغ غير المخصّص أقلّ من المبلغ الذي تطلبه، تُعيد Wave `402
INSUFFICIENT_POOL_BALANCE`. وإذا كان في المشروع أقلّ من المبلغ الذي تسترجعه، تُعيد
Wave `402 INSUFFICIENT_PROJECT_BALANCE`.

اختر **السجل** على مشروع لترى كلّ قيوده: المال المضاف، والمال المسترجَع،
والاستخدام، والمبالغ المردودة، والتعديلات. يعرض كلّ قيد الرصيد بعده.

## الفواتير

تجمع الفاتورة رسوم الاستخدام لفترة واحدة، التي ليست في فاتورة بعد. وتعرض ثلاثة
مبالغ:

| المبلغ | المعنى |
| - | - |
| الصافي | مجموع الرسوم. |
| ضريبة القيمة المضافة | 15% من المبلغ الصافي. |
| الإجمالي | المبلغ الصافي زائد الضريبة. |

تعرض قائمة **الفواتير** فترة كلّ فاتورة ومبالغها الثلاثة. وتعرض تفاصيل الفاتورة سطرًا
لكلّ نوع استخدام، مع الكمّيّة والمبلغ الصافي.

يستطيع `owner` أو `admin` اختيار **إنشاء فاتورة**. يجمع هذا رسوم الشهر الحالي حتى
الآن التي ليست في فاتورة بعد. وإذا لم توجد رسوم كهذه، لا تنشئ Wave فاتورة. والرسم
يكون في فاتورة واحدة فقط.

## واجهة الفوترة (API)

تستخدم البوّابة هذه المسارات. وهي تحتاج إلى جلسة بوّابة، لا إلى مفتاح API.

| المسار | ما يفعله |
| - | - |
| `GET /v1/billing/balance` | رصيد المحفظة. |
| `GET /v1/billing/usage` | رسوم الاستخدام، مع `from` و`to` (الافتراضي: آخر 30 يومًا). |
| `GET /v1/billing/invoices` | قائمة الفواتير. |
| `GET /v1/billing/invoices/{id}` | فاتورة واحدة مع بنودها. |
| `POST /v1/billing/topup` | بدء عمليّة شحن (`amount_sar`). |
| `GET /v1/billing/projects` | المبلغ غير المخصّص ورصيد كلّ مشروع. |
| `POST /v1/billing/projects/{projectId}/allocate` و`/deallocate` | نقل المال إلى مشروع أو منه (`amount_sar`). |

## الأخطاء

| الحالة | الرمز | متى |
| - | - | - |
| `402` | `INSUFFICIENT_CREDITS` | الرصيد 0 أو أقلّ. اشحن المحفظة. |
| `402` | `INSUFFICIENT_PROJECT_BALANCE` | ميزانيّات المشاريع تعمل وميزانيّة المشروع مستنفدة. |
| `402` | `INSUFFICIENT_POOL_BALANCE` | المبلغ غير المخصّص أقلّ من المبلغ الذي تطلبه. |
| `404` | `INVOICE_NOT_FOUND` | لا توجد فاتورة كهذه في منظّمتك. |
| `502` | `PAYMENT_FAILED` | لم يستطع مزوّد الدفع بدء عمليّة الشحن. |

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

> [card] [وضع الـ Sandbox](https://docs.wave.sa/ar/sandbox-mode.md)
>
> ما تستطيع الـ sandbox keys فعله، وما لا يُفوتَر.

> [card] [الأخطاء](https://docs.wave.sa/ar/errors.md)
>
> كلّ رموز أخطاء Wave API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.