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

# إدارة الاشتراك

> اختر خطة، اشترك عبر الدفع، أدر الإضافات، وتعامل مع الإلغاء باستخدام واجهة برمجة التطبيقات أو وحدة التحكم.

يمكنك إدارة دورة حياة الفواتير بالكامل عبر واجهة برمجة التطبيقات أو وحدة التحكم. يغطي هذا الدليل كيفية إدراج الخطط، وتقدير التكاليف، وإنشاء جلسة دفع، والتحقق من اشتراكك، وإرفاق الإضافات، والإلغاء عند الحاجة.

## المتطلبات الأساسية

* حساب Truthlocks مع مستأجر نشط.
* مفتاح API مع أذونات الفوترة. راجع [مفاتيح API](https://docs.truthlocks.com/ar/api-reference/api-keys/create.md) لإنشاء واحد.

## اختر خطة

تقدم Truthlocks خمس مستويات من الخطط. استخدم نقطة نهاية الخطط لجلب الكتالوج الكامل — هذه نقطة نهاية عامة ولا تتطلب مصادقة.

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/plans
```

```json theme={null}
[
  {
    "key": "plan_developer",
    "name": "Developer",
    "price": 0,
    "currency": "USD",
    "interval": "month",
    "features": ["500 mints/month", "Plan-dependent verifications", "Community support"],
    "highlight": false
  },
  {
    "key": "plan_starter",
    "name": "Starter",
    "price": 29,
    "currency": "USD",
    "interval": "month",
    "features": ["Higher quotas", "3 webhook endpoints", "Priority processing"],
    "highlight": true
  }
]
```

راجع [نظرة عامة على الفواتير](https://docs.truthlocks.com/ar/billing/overview.md#plan-tiers) لمقارنة جميع الخطط.

## تقدير التكاليف الخاصة بك

قبل الاشتراك، استخدم نقطة نهاية التقدير للحصول على توصية بخطة بناءً على استخدامك المتوقع. هذه أيضًا نقطة نهاية عامة.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "expected_verifications_monthly": 10000,
    "team_seats": 5,
    "webhook_endpoints_needed": 5,
    "storage_gb": 10
  }'
```

يتضمن الرد خطة موصى بها وإجمالي شهري تقديري. للحصول على تفصيل تكلفة البنود، استخدم نقطة نهاية [الفاتورة المتوقعة](https://docs.truthlocks.com/ar/api-reference/billing/projected-invoice.md) بدلاً من ذلك.

## تحقق من أسعارك الحالية

تعتمد معدلات الاستخدام الفعالة لكل مستخدم لمستأجرك على بطاقة أسعارك ومنطقتك. احصل عليها باستخدام:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/rates \
  -H "X-API-Key: tl_live_..."
```

يتضمن الرد الأسعار الأساسية وأي تعديلات تسعير إقليمية:

```json theme={null}
{
  "rate_card": { "id": "rc_default", "name": "Standard Rates", "currency": "USD" },
  "items": [
    { "metric": "attestations.mint", "unit_price": 25, "volume_min": 0, "volume_max": 0 },
    { "metric": "verifications", "unit_price": 10, "volume_min": 0, "volume_max": 0 }
  ],
  "is_default": true,
  "regional_rates": {
    "region": "TIER_1",
    "multiplier": 1.0,
    "mint_rate_cents": 25,
    "verify_rate_cents": 10
  }
}
```

> [!NOTE]
>
> إذا كان لدى مؤسستك بطاقة أسعار مخصصة تم تعيينها بواسطة مسؤول المنصة، فستظهر هذه الأسعار هنا بدلاً من الافتراضيات.

## الاشتراك في خطة

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

**1. إنشاء جلسة دفع**

استدعِ نقطة نهاية الدفع بالخطة التي تريدها وعناوين URL لإعادة التوجيه:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/checkout \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_key": "STARTER",
    "success_url": "https://yourapp.com/billing?success=true",
    "cancel_url": "https://yourapp.com/billing?canceled=true"
  }'
```

يحتوي الرد على `checkout_url` مستضاف من قبل مزود الدفع.

**2. إعادة التوجيه إلى صفحة الدفع**

أرسل المستخدم إلى `checkout_url` لإكمال الدفع.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/billing/checkout", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_key: "STARTER",
    success_url: `${window.location.origin}/billing?success=true`,
    cancel_url: `${window.location.origin}/billing?canceled=true`,
  }),
});
const { checkout_url } = await res.json();
window.location.href = checkout_url;
```

**3. تأكيد الاشتراك**

بعد الدفع، تحقق من أن الاشتراك نشط:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/subscription \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": false
}
```

> [!TIP]
>
> يمكنك اختياريًا تمرير معلمة `provider` (`stripe`، أو `paystack`، أو `flutterwave`) لتجاوز التوجيه التلقائي المستند إلى المنطقة. راجع [توجيه المزود](https://docs.truthlocks.com/ar/billing/provider-routing.md) للحصول على التفاصيل.

## إرفاق إضافات

توسع الإضافات خطتك بقدرات إضافية. قم بإرفاقها عبر API:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "addon_key": "addon_seat",
    "quantity": 2
  }'
```

إذا كان للإضافة سعر، تتضمن الاستجابة `checkout_url` لإتمام الدفع. يتم تفعيل الإضافات المجانية على الفور.

> [!NOTE]
>
> تتعدل أسعار الإضافات تلقائيًا بناءً على بلد الفوترة لمؤسستك. يدفع المستأجرون في المناطق ذات التكلفة المنخفضة سعرًا مخفضًا — على سبيل المثال، تبلغ تكلفة حزمة الامتثال 149.50 دولارًا أمريكيًا/شهريًا في نيجيريا (مضاعف 0.5x) بدلاً من السعر الأساسي البالغ 299 دولارًا أمريكيًا. راجع [تسعير الإضافات الإقليمية](https://docs.truthlocks.com/ar/billing/overview.md#regional-add-on-pricing) لجدول المستويات الكامل.

لإزالة إضافة:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"addon_key": "addon_seat"}'
```

راجع [إدارة الإضافات](https://docs.truthlocks.com/ar/api-reference/billing/addons.md) للحصول على كتالوج الإضافات الكامل وتفاصيل الاستجابة.

## مراقبة الاستخدام

تتبع استهلاك دورة الفوترة الحالية للبقاء ضمن حدود خطتك:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

للتحقق مما إذا كانت عملية معينة ضمن الحصة قبل تنفيذها:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/limits/check \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metric": "attestations.mint", "amount": 1}'
```

## فتح بوابة الفواتير

إعادة توجيه المستخدمين إلى بوابة الخدمة الذاتية لمزود الدفع الخاص بهم لتحديث طرق الدفع، أو عرض الفواتير، أو إدارة اشتراكهم:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/portal \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.com/settings/billing"
  }'
```

يتضمن الرد `portal_url`. أعد توجيه المستخدم إلى هذا العنوان URL. تنتهي صلاحية جلسات البوابة بسرعة، لذا قم بإنشاء عنوان URL جديد في كل مرة.

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

للإلغاء، اتصل بنقطة نهاية الإلغاء. يسري الإلغاء في نهاية فترة الفوترة الحالية — وستحتفظ بالوصول الكامل حتى ذلك الحين.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/cancel \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": true
}
```

بعد انتهاء الفترة، يتم تخفيض حسابك إلى خطة المطور (المجانية). لإعادة الاشتراك، أنشئ [جلسة دفع جديدة](https://docs.truthlocks.com/ar/api-reference/billing/checkout.md).

> [!WARNING]
>
> لا يمكنك التراجع عن الإلغاء عبر واجهة برمجة التطبيقات. لاستئناف اشتراكك، تحتاج إلى المرور بعملية الدفع مرة أخرى.

## ذات صلة

> [card] [نظرة عامة على الفواتير](https://docs.truthlocks.com/billing/overview.md)
>
> خطط للمستويات، والأسعار، والاستحقاقات، والإضافات.

> [card] [توجيه المزود](https://docs.truthlocks.com/billing/provider-routing.md)
>
> كيف يتم توجيه المدفوعات حسب المنطقة.

> [card] [مرجع واجهة برمجة تطبيقات الفواتير](https://docs.truthlocks.com/api-reference/billing/config.md)
>
> مرجع كامل لنقطة نهاية API الخاصة بالفوترة.

> [card] [الاستحقاقات](https://docs.truthlocks.com/api-reference/billing/entitlements.md)
>
> تحقق من ميزاتك وحصصك النشطة.


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