مقدمة

تحوّل Entitlements عملية الدفع الناجحة أو الاشتراك النشط إلى إمكانية وصول: مفتاح ترخيص في صندوق وارد العميل، أو feature flag يفحصه تطبيقك، أو دور في Discord، أو مستودع GitHub، أو قالب Notion، أو رابط remix في Framer، أو دعوة إلى محادثة Telegram، أو حزمة ملفات قابلة للتنزيل. يتولى Dodo Payments إصدار إمكانية الوصول هذه وتتبعها وإبطالها تلقائيًا مع تغيّر دورة حياة الدفع.

لوحة معلومات الاستحقاقات مع قائمة بالاستحقاقات على اليسار ونشاط المنح على اليمين — The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.

ما هي Entitlements؟

إن entitlement هو تعريف قابل لإعادة الاستخدام لشيء تسلّمه إلى العميل، مثل مفتاح ترخيص Pro، أو دور Discord باسم “Patrons”، أو إمكانية الوصول إلى مستودع GitHub خاص بك، أو حزمة كتب إلكترونية قابلة للتنزيل. تربط Entitlements بالمنتجات، ويسلّمها Dodo Payments عندما يدفع العميل. عندما يشتري العميل المنتج، ينشئ Dodo Payments grant: أي إصدار هذا entitlement لعميل واحد. يكون للـ grant إحدى أربع حالات: Pending أثناء تقدم التسليم، وDelivered بمجرد حصول العميل على إمكانية الوصول، وFailed إذا تعذر إكمال التسليم، وRevoked عند سحب إمكانية الوصول.

تتحكم Entitlements في التنفيذ (هل يملك العميل إمكانية الوصول؟). أما Credits فتتحكم في الاستهلاك (ما المقدار الذي يمكنه استخدامه؟). يمكنك ربط كليهما بالمنتج نفسه. راجع الفوترة القائمة على Credits لمعرفة المزيد عن Credits.

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

يتم تسليم كل entitlement من خلال تكامل واحد. اختر التكامل الذي يتوافق مع ما تبيعه.

License Keys

إنشاء مفاتيح ترخيص فريدة مع حدود تفعيل وانتهاء. الأفضل للبرامج، الملحقات، و CLIs.

Digital Files

سلّم الملفات القابلة للتنزيل، مثل الكتب الإلكترونية والقوالب والوسائط، باستخدام روابط تنزيل موقعة مسبقًا وتعليمات اختيارية.

Feature Flags

تحكّم في ميزات تطبيقك الخاص بناءً على عملية شراء. يتم التسليم عند الإنشاء، والتحقق من خلال API، والإبطال عند الإلغاء.

Discord

امنح العميل دورًا في خادم Discord الخاص بك عند الشراء. تتم إزالة الدور تلقائيًا عند الإلغاء.

GitHub

أضف العملاء كمتعاونين في مستودع خاص بمستوى الإذن الذي تختاره.

أضف العملاء إلى دردشة أو قناة Telegram خاصة بعد الشراء.

Framer

افتح رابط قالب Remix في Framer للعملاء الذين يدفعون.

Notion

انسخ قالب Notion إلى مساحة عمل العميل عند الشراء.

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

تتبع Grants أحداث الدفع والاشتراك نفسها التي تتلقاها باعتبارها webhooks. ينشئ Dodo Payments Grants لعمليات الشراء ويبطلها تلقائيًا، استنادًا إلى دورة حياة الدفع، لذلك لا تحتاج إلى استدعاء Grant API بنفسك.

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

يمر Grant بالحالات التالية:

Created

ينشئ Dodo Payments Grant عند اكتمال الدفع أو عند تفعيل الاشتراك. تبدأ Grants الخاصة بـ feature flags بالحالة Delivered. كما تبدأ Grants الخاصة بمفاتيح التراخيص بالحالة Delivered عندما يستخدم entitlement القيمة fulfillment_mode: auto (وهي القيمة الافتراضية). في ظل fulfillment_mode: manual، يبدأ Grant بالحالة Pending من دون مفتاح إلى أن توفّر واحدًا باستخدام Fulfill License Key Grant. يبدأ كل تكامل آخر بالحالة Pending.تكاملات OAuth (Discord وGitHub وNotion) تعرض oauth_url يزوره العميل لمنح الموافقة. يحاول Dodo Payments إنشاء هذا الرابط عند إنشاء Grant. وإذا فشل ذلك، يبقى الحقل null إلى أن يبدأ العميل تدفق القبول من رسالة التسليم الإلكترونية أو من Customer Portal. أما التكاملات المباشرة مع المنصة (Telegram وFramer وDigital Files) فتبقى في الحالة Pending فقط أثناء تجهيز التسليم، ثم تنتقل إلى Delivered.

Delivered

عند اكتمال التسليم، ينتقل Grant إلى Delivered ويتم تعيين delivered_at. يكتمل التسليم عند إنشاء مفتاح الترخيص، أو تعيين الدور، أو منح الوصول إلى المستودع، أو حل روابط الملفات، أو إنهاء تدفق OAuth.

Failed

إذا أعاد استدعاء التكامل خطأً غير قابل لإعادة المحاولة، مثل رمز OAuth مُلغى، أو إذن مرفوض، أو ملف لم يعد موجودًا، ينتقل Grant إلى Failed. ويسجل الحقلان error_code وerror_message السبب.

Revoked

عند سحب إمكانية الوصول، مثلًا بسبب إلغاء اشتراك أو إصدار رد أموال أو إبطالك Grant، ينتقل Grant إلى Revoked. ويسجل الحقل revocation_reason المُشغّل.

سلوك Grant حسب الحدث

يغيّر كل حدث دفع واشتراك Grants كما يلي:

الحدث	السلوك
`payment.succeeded` (دفع لمرة واحدة)	يصدر Grant واحدًا لكل entitlement مرتبط. ويصدر entitlement من نوع License Key Grant واحدًا لكل مفتاح.
`payment.succeeded` (دفع مرتبط باشتراك)	لا تغيير. تتولى أحداث الاشتراك أدناه قيادة هذه Grants.
`subscription.active`	يصدر Grants لأي Entitlements مرتبطة لا تملك Grant بعد، ويعيد منح Grants التي أُبطلت سابقًا للاشتراك نفسه. لا تتم إعادة منح Grants التي أُبطلت باستخدام `manual` أو `refund` أو `platform_external`.
`subscription.renewed`	لا تغيير. تستمر Grants الحالية عبر عمليات التجديد.
`subscription.past_due`	لا تغيير. تظل Grants مسلّمة طوال فترة السماح.
`subscription.on_hold`	يبطل جميع Grants المسلّمة والمعلّقة التي تحمل `revocation_reason: subscription_on_hold`.
`subscription.paused`	يبطل جميع Grants المسلّمة والمعلّقة التي تحمل `revocation_reason: SubscriptionPaused`. بخلاف أسباب الاشتراك الأخرى، تستخدم هذه القيمة PascalCase، لذا طابقها تمامًا.
`subscription.unpaused`	يعيد منح Grants التي أُبطلت سابقًا للاشتراك نفسه، بالطريقة نفسها التي يعمل بها `subscription.active`.
`subscription.cancelled`	يبطل جميع Grants التي تحمل `revocation_reason: subscription_cancelled`.
`subscription.expired`	يبطل جميع Grants التي تحمل `revocation_reason: subscription_expired`.
`subscription.plan_changed`	يبطل جميع Grants الحالية التي تحمل `revocation_reason: plan_changed`، ثم يصدر Grants لـ Entitlements الخطة الجديدة.
`refund.succeeded` (دفع لمرة واحدة)	يبطل Grants الخاصة بذلك الدفع التي تحمل `revocation_reason: refund`.
إبطال يدوي عبر API	يبطل Grant باستخدام `revocation_reason: manual`. لا تتم إعادة منح عمليات الإبطال اليدوية تلقائيًا عند تجديد الاشتراك.
تعطيل مفتاح الترخيص	بالنسبة إلى Grants الخاصة بمفاتيح التراخيص، يؤدي تعطيل المفتاح الأساسي إلى إبطال Grant باستخدام `revocation_reason: license_key_disabled`. تؤدي إعادة تفعيل المفتاح إلى استعادة Grant تلقائيًا.
اكتشاف اختلاف في المنصة	إذا خرج جانب المنصة من التكامل عن المزامنة، مثل إزالة دور Discord يدويًا، أو فقدان GitHub App للوصول إلى المستودع، أو اكتشاف عملية تسوية لهدف مفقود، فإن Dodo Payments يبطل Grant باستخدام `revocation_reason: platform_external`. ولا تتم إعادة منحه تلقائيًا عند تجديد الاشتراك إلى أن تُحل مشكلة المنصة.

تكون Grants المدفوعة بالاشتراك idempotent لكل (entitlement, customer, subscription)، لذلك لا تنشئ عمليات التجديد وإعادة التفعيل Grants مكررة. أما Grants لمرة واحدة فتكون idempotent لكل (entitlement, customer, payment).

أنشئ أول Entitlement لك

Open Entitlements

انتقل إلى Entitlements في لوحة التحكم وانقر على + لإنشاء entitlement.

Pick an Integration

اختر نوع التكامل: License Key أو Digital Files أو Feature Flag أو Discord أو GitHub أو Telegram أو Figma أو Framer أو Notion. بالنسبة إلى تكاملات المنصات، صِل حسابك أولًا إذا لم تكن قد فعلت ذلك من قبل.

Configure Delivery

املأ الحقول الخاصة بالتكامل. على سبيل المثال، يطلب GitHub مستودعًا ومستوى إذن، ويطلب Discord خادمًا ودورًا اختياريًا، بينما يطلب License Key حدًا لعدد عمليات التفعيل ومدة الترخيص.

نموذج New Entitlement مع محدد التكامل وحقول الإعداد — Creating a GitHub entitlement. Each integration shows the fields it needs.

Save

انقر على Create Entitlement. يمكنك الآن ربط entitlement بأي منتج.

ربط Entitlements بالمنتجات

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

لوحة اختيار Entitlements للمنتج تعرض مربعات اختيار لكل entitlement متاح — Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.

تجربة العميل

البريد الإلكتروني وCustomer Portal

بعد الشراء، يتلقى العميل رسالة تسليم إلكترونية تتضمن مفتاح الترخيص أو روابط التنزيل أو روابط دعوة OAuth أو دعوة المنصة التي تنطبق على Entitlements الموجودة في المنتج. وتظل التفاصيل نفسها متاحة في Customer Portal، ضمن سجل الطلبات، ما دام Grant نشطًا.

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

يتطلب وصول المشتركين إلى Discord وGitHub وNotion أن يسمح العميل لـ Dodo Payments بمنح هذا الوصول. تبقى هذه Grants في الحالة Pending إلى أن يكمل العميل تدفق OAuth من الرابط الموجود في بريده الإلكتروني أو في Customer Portal. بعد منح العميل الموافقة، ينتقل Grant إلى Delivered ويجهّز Dodo Payments إمكانية الوصول إلى المنصة.

الإبطال

عند إبطال Grant، يزيل Dodo Payments إمكانية الوصول من المنصة: إذ يزيل دور Discord أو يزيل متعاون GitHub أو يعطّل مفتاح الترخيص. ويرى العميل التغيير في Customer Portal.

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

إدارة Grants

افتح أي entitlement من لوحة التحكم لعرض Grants الخاصة به. تعرض لوحة التفاصيل إجمالي Grants الممنوحة، وفلترًا للحالة، وصفًا واحدًا لكل Grant يتضمن العميل وتاريخ الوصول والحالة وإجراء Revoke. لإدارة Grants برمجيًا، أدرجها باستخدام فلتر status وأبطل Grant واحدًا باستخدام معرّفه:

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('entg_xyz789', {
  id: 'ent_abc123',
});

# Assumes client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
grants = client.entitlements.grants.list(
    "ent_abc123",
    status="Delivered",
)

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

// Assumes client := dodopayments.NewClient() and ctx := context.Background().
grants, err := client.Entitlements.Grants.List(
  ctx, "ent_abc123",
  dodopayments.EntitlementGrantListParams{
    Status: dodopayments.F(dodopayments.EntitlementGrantListParamsStatusDelivered),
  },
)
if err != nil {
  panic(err.Error())
}
fmt.Println(len(grants.Items))

_, err = client.Entitlements.Grants.Revoke(ctx, "ent_abc123", "entg_xyz789")

إدارة API

Create Entitlement

أنشئ entitlement من أي نوع من أنواع التكامل.

List Entitlements

أدرج Entitlements مع تصفيتها حسب نوع التكامل.

Get Entitlement

استرجع entitlement وإعداده الذي تمت تسويته.

Update Entitlement

حدّث الاسم أو الوصف أو إعداد التكامل.

Delete Entitlement

احذف entitlement حذفًا ناعمًا. لا يتم إبطال Grants الحالية، لكن Dodo Payments لم يعد يديرها.

Upload File

ارفع ملفًا بحجم يصل إلى 500 MiB إلى entitlement من نوع Digital Files.

List Grants

أدرج Grants الخاصة بـ entitlement، مع تصفيتها حسب الحالة والعميل.

Revoke Grant

أبطل Grant واحدًا يدويًا.

Webhooks

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

الحدث	يحدث عند
`entitlement_grant.created`	إنشاء Grant. تصل Grants الخاصة بمفاتيح التراخيص التي تم تنفيذها تلقائيًا وGrants الخاصة بـ feature flags بالحالة `Delivered`. أما Grants الخاصة بمفاتيح التراخيص التي تم تنفيذها يدويًا وكل تكامل آخر فتصل بالحالة `Pending`، ثم تنتقل إلى `Delivered` بعد نجاح استدعاء المنصة أو، بالنسبة إلى التكاملات المستندة إلى OAuth، بعد منح العميل الموافقة.
`entitlement_grant.delivered`	انتقال Grant موجود إلى `Delivered`، بحيث يحصل العميل الآن على إمكانية الوصول. لا يطلق Grant الموجود بالحالة `Delivered` عند الإنشاء سوى `created`.
`entitlement_grant.failed`	تعذّر تسليم Grant. افحص `error_code` و`error_message`.
`entitlement_grant.revoked`	تم سحب إمكانية الوصول. افحص `revocation_reason`.

Entitlement Grant Webhook Payloads

اعرض مخطط الحمولة الكامل والأحداث النموذجية ومرجع revocation_reason.

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

استخدم entitlement واحدًا لكل قناة تسليم. لا تشارك entitlement واحدًا لـ Discord بين منتجات ذات نوايا مختلفة للأدوار. أنشئ entitlement واحدًا لكل دور حتى يظل الإبطال نظيفًا.
اختبر في وضع الاختبار أولًا. أنشئ entitlement، واربطه بمنتج اختباري، ونفّذ عملية checkout، وراقب انتقال Grant من Pending إلى Delivered. ثم ألغِ الاشتراك الاختباري وتأكد من إبطال Grant.
استمع إلى entitlement_grant.delivered، وليس payment.succeeded. قد تنجح عملية الدفع قبل اكتمال التنفيذ، خصوصًا في تدفقات OAuth. انتظر وصول Grant إلى Delivered قبل فتح الميزات التابعة في أنظمتك الخاصة. أما Grant الذي يتم تسليمه عند الإنشاء، مثل مفتاح ترخيص يتم تنفيذه تلقائيًا أو feature flag، فيصل كـ entitlement_grant.created مع status: "Delivered" بدلًا من ذلك.
تعامل مع entitlement_grant.failed باعتباره قابلًا للإجراء. يعني Grant الفاشل أن العميل دفع لكنه لم يحصل على إمكانية الوصول. اعرض هذه Grants على فريق الدعم أو شغّل إعادة منح.
اربط revocation_reason بتدفقات الاحتفاظ بالعملاء لديك. يمكن استرداد إبطال subscription_on_hold، لأن العميل قد يحدّث بطاقته. أما إبطال manual فهو مقصود. تعامل معهما بشكل مختلف في رسائل العملاء.
لا تبطل إمكانية الوصول عند subscription.past_due. يفتح ذلك الحدث فترة سماح، ويحتفظ العميل بإمكانية الوصول حتى انتهاء المدة. انتظر subscription.on_hold أو subscription.cancelled.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

ما هي Entitlements؟

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

License Keys

Digital Files

Feature Flags

Discord

GitHub

Telegram

Framer

Notion

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

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

سلوك Grant حسب الحدث

أنشئ أول Entitlement لك

ربط Entitlements بالمنتجات

تجربة العميل

البريد الإلكتروني وCustomer Portal

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

الإبطال

إدارة Grants

إدارة API

Create Entitlement

List Entitlements

Get Entitlement

Update Entitlement

Delete Entitlement

Upload File

List Grants

Revoke Grant

Webhooks

Entitlement Grant Webhook Payloads

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