الاستخدام والحساب

الفوترة

ما اشتركت فيه مساحة العمل، وما تراكم في الفترة الحالية، والكشوف وراءه. وهذا سطح إدارة حساب: لا يصل إليه أي مفتاح API.

ما الموجود هنا

نظرة عامة واحدة، وتعديل واحد للملف، وسجل الكشوف. ويُقرأ كل شيء ببيانات اعتماد مساحة العمل نفسها — ولا يوجد هنا مسار عابر للمستأجرين.

GET/v1/billingPATCH/v1/billing/customerGET/v1/billing/invoicesGET/v1/billing/invoices/{invoiceId}

رموز الجلسة فقط

المسارات الأربعة معلنة لـ sessionToken وحده وتتطلب billing.manage. ولا يصل إليها مفتاح API إطلاقًا، فأخفِ الوجهة عن دور لا يملك التصريح بدل ترك الطلب يعود بـ 403 — وأعد الفحص في اللوحة نفسها، لأن رابطًا محفوظًا يستحق تفسيرًا لا طلبًا فاشلًا. انظر المصادقة.

curl

# No API key reaches this: billing is account-management surface.
curl https://whats.azzamkh.sa/api/v1/billing \
  -H "Authorization: Bearer <access token>" \
  -H "X-Workspace-Id: ws_..."

# 200 OK — every amount is a MINOR-UNIT integer beside its own currency,
# and null means NOT PRICED, which is a different fact from 0.
# {
#   "customer": {
#     "id": "bcu_...", "provider": "manual", "name": "...",
#     "email": "...", "currency": null, ...
#   },
#   "subscription": {
#     "status": "active",
#     "plan": { "code": "standard", "name": "Standard", ... },
#     "pending_plan": null,
#     "current_period_start": "2026-08-01T00:00:00.000Z",
#     "current_period_end": "2026-09-01T00:00:00.000Z",
#     "canceled_at": null,
#     "items": [ ... ]
#   },
#   "latest_invoice": {
#     "id": "inv_...", "number": null, "status": "open",
#     "currency": null, "subtotal_minor": null, "total_minor": null,
#     "unpriced_lines": 1, "period_end": "2026-09-01T00:00:00.000Z", ...
#   }
# }

قراءة المبالغ

كل مبلغ عدد صحيح بالوحدة الصغرى. ولا يوجد أُسّ يُفترض: للدينار الأردني ثلاث خانات عشرية وللين الياباني لا شيء، فالقسمة على 100 في أي مكان خاطئة لكليهما.
كل مبلغ يحمل currency الخاصة به. ولا توجد عملة للنشر ولا عملة افتراضية — اقرأ التي بجوار الرقم.
القيمة null تعني «غير مسعّر»، وهي حقيقة مختلفة عن 0. فالخطة المجانية تكلّف صفرًا بحق، أما السطر غير المسعّر فلم يُعطَ مبلغًا قط.
لا شيء يُعاد اشتقاقه في العميل. لا الفترة — فالخادم يثبّت طرفيها على منتصف ليل بالتوقيت العالمي ويقصّ يوم الشهر كي لا ينزلق التجديد — ولا مبلغ سطر، ولا الإجمالي.

الإجمالي كامل بقدر ما يقول unpriced_lines

يجمع total_minor السطور المسعّرة، ويعدّ unpriced_lines ما تركه منها. اعرض العدد بجوار كل إجمالي، وإلا قرأ العميل رسم الاشتراك على أنه الفاتورة كلها. وهو اليوم 1 على الأقل عادةً: فكل اشتراك يحمل سطر استهلاك ولا يسعّر أي مسار الاستهلاك بعد، ولهذا يُقرأ هذا السطح كبيان استخدام لا كفاتورة.

الاستجابات

الاشتراك

الحقل	الوصف
status	حالة الاشتراك نفسه.
plan	الخطة السارية الآن.
pending_plan	تغيير خطة تقرّر ولم يُطبَّق. انظر أدناه.
current_period_start, current_period_end	طرفا الفترة الحالية. والقيمة period_end حصرية — فلا تُرجعها يومًا لتسميتها.
canceled_at	متى أُلغي، إن أُلغي.
items	سطور الاشتراك، ولكل سطر مبلغه وعملته.

الحقل pending_plan ليس تفضيلًا

هو تغيير خطة موقوف ليُطبَّق في نهاية الفترة. ولا يستطيع العميل إلغاءه وربما لم يطلبه، فمكانه أعلى الشاشة لا داخل بطاقة. وتكون effective_at عادةً null — فالتغيير الموقوف لنهاية الفترة ليس له لحظة خاصة — فسمِّ نهاية الفترة بدل طباعة تاريخ فارغ.

الفاتورة

الحقل	النوع	الوصف
number	string \| null	يُصكّ عند الإصدار، وهو ليس متسلسلًا بلا فجوات عن قصد. والفاتورة هنا ليست مستندًا ضريبيًا.
status	string	موضعها في دورة حياة الفاتورة.
period_start, period_end	string	الفترة التي تغطيها. والقيمة period_end حصرية.
subtotal_minor, total_minor	number \| null	كلاهما null حين لا يكون شيء في الفاتورة مسعّرًا.
unpriced_lines	number	كم سطرًا تركه الإجمالي. اعرضه دائمًا بجوار الإجمالي.
issued_at, due_at, paid_at, voided_at	string \| null	متى أُصدرت، ومتى تستحق، ومتى دُفعت، ومتى أُبطلت.
lines	array	موجودة في مسار التفاصيل، وغائبة عن القائمة.

تُجمَّد الفاتورة عند إغلاق فترتها: تظل تقول الشيء نفسه بعد تعديل خطة أو تغيّر سعر. ويحمل كل سطر quantity وmetric اختياريًا، وunit_amount_minor وamount_minor بقيمة null لكل ما هو غير مسعّر.

ملف الفوترة

يأخذ PATCH /v1/billing/customer الاسم والبريد والرقم الضريبي والدولة والعملة والعنوان. وكل الحقول تقبل null، وإرسال null يمسحها. أما provider فللقراءة فقط.

تغيير الخطة

لا يوجد تغيير خطة ذاتي الخدمة، وهذا مقصود: فمع مزوّد manual يتم التحصيل خارج هذا النظام، وزر الترقية سيلزم العميل بشيء لا تستطيع المنصّة إتمامه. وكتالوج الخطط هو ما تُبنى منه أي مقارنة، وتغطي صفحة الخطط والحصص ما تسمح به الخطة الحالية فعلًا.

الأخطاء المهمة هنا

الرمز	HTTP	متى يحدث
BILLING_SUBSCRIPTION_NOT_FOUND	404	لا يوجد اشتراك فعّال لمساحة العمل هذه.
BILLING_INVOICE_NOT_FOUND	404	لا توجد فاتورة بهذا المعرّف في مساحة العمل هذه.
BILLING_INVOICE_INVALID_STATE	409	لا تستطيع الفاتورة الانتقال إلى تلك الحالة من حالتها الحالية. ويحمل details.allowed الانتقالات المسموحة، وهو المرجع — إذ لا ينشر أي مسار الجدول مسبقًا، فاعرض ما يقوله الرفض.
BILLING_PROVIDER_UNAVAILABLE	503	مزوّد الفوترة غير متاح. وقابل لإعادة المحاولة.
FORBIDDEN	403	المتصل لا يملك billing.manage.

كل رمز وحالته في صفحة الأخطاء.