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

# مقدمة

> تسليم تلقائي لمفاتيح الترخيص، الملفات القابلة للتنزيل، العلامات المميزة للميزات، والوصول إلى منصات مثل Discord، GitHub، Telegram، Framer، وNotion عند دفع العملاء.

<Info>
  الامتيازات تحول الدفع الناجح أو الاشتراك النشط إلى وصول حقيقي: مفتاح ترخيص في صندوق بريد العميل، علامة مميزة لميزة يتفقدها تطبيقك، دور في Discord، مستودع GitHub، قالب Notion، رابط Remix في Framer، دعوة دردشة في Telegram، أو حزمة ملفات قابلة للتنزيل. يقوم Dodo Payments بإصدار وتتبع وإلغاء هذا الوصول تلقائيًا مع تغييرات دورة الدفع.
</Info>

<Frame caption="The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.">
  <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/list.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=12a326205f64d1e71485bce46114d296" alt="لوحة معلومات الاستحقاقات مع قائمة بالاستحقاقات على اليسار ونشاط المنح على اليمين" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1195" data-path="images/entitlements/list.png" />
</Frame>

## ما هي الاستحقاقات؟

**الاستحقاق** هو تعريف قابل لإعادة الاستخدام لشيء تقدمه للعميل: مفتاح ترخيص Pro، دور "Patrons" في Discord، الوصول إلى مستودع GitHub الخاص بك، أو حزمة كتب إلكترونية قابلة للتنزيل. تقوم بإرفاق الاستحقاقات بالمنتجات، وتتعامل Dodo Payments مع الباقي.

عندما يشتري العميل المنتج، تنشئ Dodo Payments **منحة**، وهي إصدار استحقاق مخصص لذلك العميل. تمر المنح بعدة حالات: `pending` أثناء تقدم التسليم، `delivered` بمجرد أن يحصل العميل على الوصول، `failed` إذا لم يكتمل التسليم، و `revoked` عند سحب الوصول.

<Tip>
  تتحكم الاستحقاقات في **التنفيذ** (هل لدى العميل وصول؟). تتحكم الأرصدة في **الاستهلاك** (كم يمكنهم استخدامه؟). يمكن إرفاق كلاهما بنفس المنتج. راجع [الفوترة المعتمدة على الأرصدة](/features/credit-based-billing) للأرصدة.
</Tip>

## عمليات دمج متاحة

تقوم Dodo Payments بتسليم كل استحقاق من خلال تكامل مخصص. اختر التكامل الذي يتناسب مع ما تبيعه.

<CardGroup cols={2}>
  <Card title="License Keys" icon="key" href="/features/license-keys">
    إنشاء مفاتيح ترخيص فريدة مع حدود تفعيل وانتهاء. الأفضل للبرامج، الملحقات، و CLIs.
  </Card>

  <Card title="Digital Files" icon="download" href="/features/digital-product-delivery">
    تسليم الملفات القابلة للتنزيل (الكتب الإلكترونية، القوالب، الوسائط) مع عناوين URL مسبقة التوقيع وتعليمات اختيارية.
  </Card>

  <Card title="Feature Flags" icon="flag" href="/features/entitlements/feature-flags">
    قيد الميزات في تطبيقك عند الشراء. يتم التوصيل فورًا، التحقق عبر API، الإلغاء عند الإلغاء.
  </Card>

  <Card title="Discord" icon="discord" href="/features/entitlements/discord">
    امنح العميل دورًا في خادم Discord الخاص بك عند الشراء. يتم الإلغاء تلقائيًا عند الإلغاء.
  </Card>

  <Card title="GitHub" icon="github" href="/features/entitlements/github">
    أضف العملاء كمتعاونين في مستودع خاص بمستوى الإذن الذي تختاره.
  </Card>

  <Card title="Telegram" icon="telegram" href="/features/entitlements/telegram">
    أضف العملاء إلى دردشة أو قناة Telegram خاصة بعد الشراء.
  </Card>

  <Card title="Framer" icon="puzzle-piece" href="/features/entitlements/framer">
    افتح رابط قالب Remix في Framer للعملاء الذين يدفعون.
  </Card>

  <Card title="Notion" icon="book" href="/features/entitlements/notion">
    انسخ قالب Notion إلى مساحة عمل العميل عند الشراء.
  </Card>
</CardGroup>

***

## كيف تعمل المنح

يتم تشغيل المنح من خلال نفس أحداث الدفع والاشتراكات التي تتلقاها بالفعل كخدمات ويب. ليس لديك حاجة لاستدعاء API للمنح بنفسك للشراء. Dodo Payments ينشئ ويلغي المنح تلقائيًا بناءً على دورة الدفع الأساسية.

### دورة حياة المنحة

<Steps>
  <Step title="Created">
    يتم إنشاء منحة عند اكتمال الدفع أو تفعيل الاشتراك. مفاتيح الترخيص والعلامات المميزة للميزات تنتقل مباشرة إلى `delivered`. تبدأ كل التكاملات الأخرى في `pending`. تتضمن التكاملات التي تعتمد على OAuth (Discord، GitHub، Notion) `oauth_url` يجب على العميل زيارتها لإكمال الموافقة. التكاملات المباشرة مع المنصات (Telegram، Framer، Digital Files) تبقى في `pending` فقط لفترة وجيزة أثناء توفير التسليم، ثم تتحول إلى `delivered`.
  </Step>

  <Step title="Delivered">
    عندما يكتمل التسليم (تم إنشاء مفتاح ترخيص، تم تعيين دور، تم منح وصول إلى المستودع، تم حل روابط الملفات، تم إكمال OAuth)، تنتقل المنحة إلى `delivered` ويتم تعيين `delivered_at`.
  </Step>

  <Step title="Failed">
    إذا أرجع استدعاء التكامل خطأ غير قابل للتكرار (تم إلغاء رمز OAuth، تم رفض إذن، لم يعد الملف موجودًا)، تنتقل المنحة إلى `failed`. يتم التقاط السبب في `error_code` و`error_message`.
  </Step>

  <Step title="Revoked">
    عند سحب الوصول (تم إلغاء الاشتراك، تم إصدار رد أموال، أو الإلغاء بمبادرة من التاجر)، تنتقل المنحة إلى `revoked`. يتم تسجيل الزناد في حقل `revocation_reason`.
  </Step>
</Steps>

### سلوك المنحة حسب الحدث

| الحدث                                     | السلوك                                                                                                                                                                                                                                                                                              |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (دفعة واحدة)          | إصدار منحة واحدة لكل امتياز ملحق.                                                                                                                                                                                                                                                                   |
| `payment.succeeded` (دفع مرتبط بالاشتراك) | لا يوجد عملية. المنح مدفوعة بحدث الاشتراك أدناه.                                                                                                                                                                                                                                                    |
| `subscription.active`                     | إصدار منح لأي امتيازات مرتبطة لا تملك واحدة بالفعل. إعادة منح أي منح تم إلغاؤها سابقًا لنفس الاشتراك.                                                                                                                                                                                               |
| `subscription.renewed`                    | لا يوجد عملية. تبقى المنح الحالية ثابتة مع التجديدات.                                                                                                                                                                                                                                               |
| `subscription.on_hold`                    | إلغاء جميع المنح التي تم تسليمها والمعلقة. `revocation_reason: subscription_on_hold`.                                                                                                                                                                                                               |
| `subscription.cancelled`                  | إلغاء الكل. `revocation_reason: subscription_cancelled`.                                                                                                                                                                                                                                            |
| `subscription.expired`                    | إلغاء الكل. `revocation_reason: subscription_expired`.                                                                                                                                                                                                                                              |
| `subscription.plan_changed`               | إلغاء جميع المنح الحالية، ثم إصدار منح لامتيازات الخطة الجديدة. `revocation_reason: plan_changed`.                                                                                                                                                                                                  |
| `refund.succeeded` (دفعة واحدة)           | إلغاء المنح لتلك الدفعة. `revocation_reason: refund`.                                                                                                                                                                                                                                               |
| إلغاء API يدوي                            | إلغاء مع `revocation_reason: manual`. لا يتم إعادة منح الإلغاءات اليدوية تلقائيًا عند تجديد الاشتراك.                                                                                                                                                                                               |
| تم تعطيل مفتاح الترخيص                    | بالنسبة للمنح التي تعتمد على مفتاح الترخيص، فإن تعطيل المفتاح الأساسي يلغي المنحة مع `revocation_reason: license_key_disabled`. يتم تنشيط المنحة تلقائيًا إذا تم إعادة تفعيل المفتاح.                                                                                                               |
| تم اكتشاف انجراف في المنصة                | إذا انحرفت الجانب المنصة للتكامل عن التزامن (تم إزالة دور في Discord يدويًا، فقد الوصول إلى مستودع في تطبيق GitHub، أو اكتشاف تمرير تصالح يفقد الهدف)، تلغى المنحة مع `revocation_reason: platform_external`. لن يتم إعادة منحها تلقائيًا عند تجديد الاشتراك حتى يتم حل المشكلة الأساسية في المنصة. |

<Note>
  المنح التي تعتمد على الاشتراك تكون فائضة لكل `(entitlement, customer, subscription)`; لا تنشئ التجديدات وإعادة التفعيل منحًا مكررة. تكون المنح الفردية فائضة لكل `(entitlement, customer, payment)`.
</Note>

***

## أنشئ أول امتياز لك

<Steps>
  <Step title="Open Entitlements">
    انتقل إلى **الامتيازات** في لوحة تحكم Dodo Payments وانقر على **+** لإنشاء امتياز جديد.
  </Step>

  <Step title="Pick an integration">
    اختر نوع التكامل: مفتاح ترخيص، ملفات رقمية، علامة مميزة للميزات، Discord، GitHub، Telegram، Framer، أو Notion. بالنسبة لتكاملات المنصة، قم بتوصيل حسابك أولاً إذا لم تكن قد فعلت ذلك من قبل.
  </Step>

  <Step title="Configure delivery">
    املأ الحقول الخاصة بالتكامل. على سبيل المثال، يطلب GitHub مستودعًا ومستوى إذن؛ يطلب Discord خادمًا ودورًا اختياريًا؛ يطلب مفتاح الترخيص حدود تنشيط وانتهاء الصلاحية.

    <Frame caption="Creating a GitHub entitlement. Each integration shows the fields it needs.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/github/create.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=722e925ec5158a5d16c58213132ccb9d" alt="نموذج امتياز جديد مع موحد تكامل وحقول تكوين" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1130" data-path="images/entitlements/github/create.png" />
    </Frame>
  </Step>

  <Step title="Save">
    احفظ الامتياز. يمكنك الآن إرفاقه بأي منتج.
  </Step>
</Steps>

## إرفاق الامتيازات بالمنتجات

افتح منتجًا، وقم بتوسيع **إعدادات متقدمة → الامتيازات والائتمانات**، وحدد الامتيازات التي يجب تسليمها عند شراء المنتج. يمكن أن يسلم منتج واحد عدة امتيازات في وقت واحد. على سبيل المثال، يمكن أن تشمل خطة Pro مفتاح ترخيص، وصول إلى GitHub، ودور في Discord.

<Frame caption="Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.">
  <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/attach-to-product.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=965ad78262791fa8dbb712b4fdf89538" alt="لوحة اختيار امتياز المنتج تعرض مربعات اختيار لكل امتياز متوفر" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1197" data-path="images/entitlements/attach-to-product.png" />
</Frame>

***

## تجربة العميل

### البريد الإلكتروني وبوابة العميل

يتلقى العملاء بريدًا إلكترونيًا للتسليم بعد الشراء يحتوي على مفتاح الترخيص، وروابط التحميل، وروابط الدعوة لـ OAuth، أو دعوة للمنصة، أيًا ما ينطبق على الامتيازات الموجودة في المنتج. تبقى نفس التفاصيل متاحة إلى الأبد من [بوابة العملاء](/features/customer-portal) تحت سجل الطلبات الخاص بهم.

### التسليم المستند إلى OAuth

يتطلب الوصول للمشتركين في Discord وGitHub وNotion من العميل تفويض Dodo Payments لمنحهم الوصول. تبقى هذه المنح في حالة `pending` حتى يكمل العميل تدفق OAuth باستخدام الرابط من بريده الإلكتروني أو بوابة العملاء. بمجرد التفويض، تنتقل المنحة إلى `delivered` ويتم توفير الوصول إلى المنصة فورًا.

### الإلغاء

تم إزالة المنح الملغاة على مستوى المنصة: يتم إزالة دور Discord، ويتم إزالة المتعاون في GitHub، ويتم تعطيل مفتاح الترخيص. يرى العملاء هذا التغيير منعكسًا في بوابة العملاء.

<Warning>
  بالنسبة للملفات الرقمية، يلغي الإلغاء الوصول إلى عناوين URL الموقعة مسبقًا في المستقبل ولكنه لا يبطل النسخ التي قام العميل بتنزيلها بالفعل. خطط محتوى بوابة المحتوى وفقًا لذلك.
</Warning>

***

## إدارة المنح

افتح أي امتياز من لوحة التحكم لرؤية منحته. تعرض لوحة تفاصيل المنحة إجمالي المنح ومرشحات الحالة ومعلومات العميل وتواريخ التسليم وإجراء الإلغاء.

يمكنك أيضًا إدارة المنح برمجيًا:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  });

  // List grants for an entitlement
  const grants = await client.entitlements.grants.list('ent_abc123', {
    status: 'Delivered',
  });

  // Revoke a single grant
  await client.entitlements.grants.revoke('grant_xyz789', {
    id: 'ent_abc123',
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.grants.list(
      "ent_abc123",
      status="Delivered",
  )

  client.entitlements.grants.revoke(
      "grant_xyz789",
      id="ent_abc123",
  )
  ```

  ```go Go theme={null} theme={null}
  grants, _ := client.Entitlements.Grants.List(
    ctx, "ent_abc123",
    dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
  )

  _, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
  ```
</CodeGroup>

***

## إدارة API

<CardGroup cols={2}>
  <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
    أنشئ امتيازًا جديدًا من أي نوع تكامل.
  </Card>

  <Card title="List Entitlements" icon="list" href="/api-reference/entitlements/list-entitlements">
    إدراج الامتيازات مع التصفية حسب نوع التكامل.
  </Card>

  <Card title="Get Entitlement" icon="magnifying-glass" href="/api-reference/entitlements/get-entitlement">
    استعراض امتياز وتكوينه المحلل.
  </Card>

  <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
    تحديث الاسم، الوصف، أو تكوين التكامل.
  </Card>

  <Card title="Delete Entitlement" icon="trash" href="/api-reference/entitlements/delete-entitlement">
    حذف امتياز بشكل ناعم؛ لا تتأثر الامتيازات الحالية.
  </Card>

  <Card title="Upload File" icon="upload" href="/api-reference/entitlements/upload-file">
    رفع ملف إلى امتياز الملفات الرقمية (حتى 500 ميجابايت).
  </Card>

  <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
    إدراج جميع المنح لامتياز مع فلترة الحالة والعميل.
  </Card>

  <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
    الغاء منحة واحدة يدويًا.
  </Card>
</CardGroup>

***

## خدمات ويب

يقوم Dodo Payments بتشغيل أربع أحداث ويب لحالة المنحة. اشترك في هذه الأحداث للحفاظ على توافق تطبيقك مع ما يمكن لكل عميل الوصول إليه.

| الحدث                         | يعمل عند                                                                                                                                                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created`   | تم إنشاء منحة جديدة. تصل منح مفتاح الترخيص `delivered`؛ تصل كل تكامل أخرى `pending` وتنتقل إلى `delivered` بمجرد نجاح استدعاء المنصة (أو بالنسبة للتكاملات المستندة إلى OAuth، بمجرد أن يمنح العميل التفويض). |
| `entitlement_grant.delivered` | تنتقل المنحة إلى التسليم. العميل الآن لديه إمكانية الوصول.                                                                                                                                                    |
| `entitlement_grant.failed`    | لم يمكن توصيل المنحة. تحقق من `error_code` و`error_message`.                                                                                                                                                  |
| `entitlement_grant.revoked`   | تم سحب الوصول. تحقق من `revocation_reason`.                                                                                                                                                                   |

<Card title="Entitlement Grant Webhook Payloads" icon="bell" href="/developer-resources/webhooks/intents/entitlement-grant">
  استعرض المخطط الكامل للحزمة، الأحداث النموذجية، ومرجع `revocation_reason`.
</Card>

***

## أفضل الممارسات

* **استخدم امتيازًا واحدًا لكل قناة تسليم.** لا تشارك امتياز Discord واحد عبر منتجات ذات نوايا دور مختلفة؛ أنشئ واحدًا لكل دور لقيامك بإلغاء نظيف.
* **اختبر أولاً في وضع الاختبار.** أنشئ الامتياز، قم بإرفاقه بمنتج اختبار، نفذ عملية الشراء، راقب انتقال المنحة عبر `pending → delivered`. تأكد من أن إلغاء الاشتراك التجريبي يلغي المنحة.
* **استمع إلى `entitlement_grant.delivered`، وليس `payment.succeeded`.** يمكن أن ينجح الدفع قبل انتهاء التوفيق (خاصة لتدفقات OAuth). انتظر حتى حدث التسليم قبل فتح ميزات تبعية في أنظمتك الخاصة.
* **تعامل مع `entitlement_grant.failed` كقابل للتنفيذ.** يعني منحة فاشلة أن العميل دفع ولم يحصل على الوصول. اعرض هذه الأمور لفريق الدعم الخاص بك أو قم بتشغيل إعادة المنح.
* **قم بتخطيط `revocation_reason` لتدفقات الاحتفاظ الخاصة بك.** الإلغاء الذي يتم بالاستخدام `subscription_on_hold` يمكن استرداده (قد يقوم العميل بتحديث بطاقته). الإلغاء الذي يتم بالاستخدام `manual` مقصود. تعامل معها بشكل مختلف في اتصالات العملاء.