سلّم مفاتيح التراخيص والملفات القابلة للتنزيل وfeature flags وإمكانية الوصول إلى Discord وGitHub وTelegram وFramer وNotion تلقائيًا عند دفع العملاء.
تحوّل 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.
إن entitlement هو تعريف قابل لإعادة الاستخدام لشيء تسلّمه إلى العميل، مثل مفتاح ترخيص Pro، أو دور Discord باسم “Patrons”، أو إمكانية الوصول إلى مستودع GitHub خاص بك، أو حزمة كتب إلكترونية قابلة للتنزيل. تربط Entitlements بالمنتجات، ويسلّمها Dodo Payments عندما يدفع العميل.عندما يشتري العميل المنتج، ينشئ Dodo Payments grant: أي إصدار هذا entitlement لعميل واحد. يكون للـ grant إحدى أربع حالات: Pending أثناء تقدم التسليم، وDelivered بمجرد حصول العميل على إمكانية الوصول، وFailed إذا تعذر إكمال التسليم، وRevoked عند سحب إمكانية الوصول.
تتحكم Entitlements في التنفيذ (هل يملك العميل إمكانية الوصول؟). أما Credits فتتحكم في الاستهلاك (ما المقدار الذي يمكنه استخدامه؟). يمكنك ربط كليهما بالمنتج نفسه. راجع الفوترة القائمة على Credits لمعرفة المزيد عن Credits.
تتبع Grants أحداث الدفع والاشتراك نفسها التي تتلقاها باعتبارها webhooks. ينشئ Dodo Payments Grants لعمليات الشراء ويبطلها تلقائيًا، استنادًا إلى دورة حياة الدفع، لذلك لا تحتاج إلى استدعاء Grant API بنفسك.
ينشئ 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.
2
Delivered
عند اكتمال التسليم، ينتقل Grant إلى Delivered ويتم تعيين delivered_at. يكتمل التسليم عند إنشاء مفتاح الترخيص، أو تعيين الدور، أو منح الوصول إلى المستودع، أو حل روابط الملفات، أو إنهاء تدفق OAuth.
3
Failed
إذا أعاد استدعاء التكامل خطأً غير قابل لإعادة المحاولة، مثل رمز OAuth مُلغى، أو إذن مرفوض، أو ملف لم يعد موجودًا، ينتقل Grant إلى Failed. ويسجل الحقلان error_code وerror_message السبب.
4
Revoked
عند سحب إمكانية الوصول، مثلًا بسبب إلغاء اشتراك أو إصدار رد أموال أو إبطالك Grant، ينتقل Grant إلى Revoked. ويسجل الحقل revocation_reason المُشغّل.
يصدر Grant واحدًا لكل entitlement مرتبط. ويصدر entitlement من نوع License Key Grant واحدًا لكل مفتاح.
payment.succeeded (دفع مرتبط باشتراك)
لا تغيير. تتولى أحداث الاشتراك أدناه قيادة هذه Grants.
subscription.active
يصدر Grants لأي Entitlements مرتبطة لا تملك Grant بعد، ويعيد منح Grants التي أُبطلت سابقًا للاشتراك نفسه. لا تتم إعادة منح Grants التي أُبطلت باستخدام manual أو refund أو platform_external.
subscription.renewed
لا تغيير. تستمر Grants الحالية عبر عمليات التجديد.
يبطل جميع 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).
انتقل إلى Entitlements في لوحة التحكم وانقر على + لإنشاء entitlement.
2
Pick an Integration
اختر نوع التكامل: License Key أو Digital Files أو Feature Flag أو Discord أو GitHub أو Telegram أو Figma أو Framer أو Notion. بالنسبة إلى تكاملات المنصات، صِل حسابك أولًا إذا لم تكن قد فعلت ذلك من قبل.
3
Configure Delivery
املأ الحقول الخاصة بالتكامل. على سبيل المثال، يطلب GitHub مستودعًا ومستوى إذن، ويطلب Discord خادمًا ودورًا اختياريًا، بينما يطلب License Key حدًا لعدد عمليات التفعيل ومدة الترخيص.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
انقر على Create Entitlement. يمكنك الآن ربط entitlement بأي منتج.
افتح منتجًا، وانتقل إلى قسم Entitlements، وحدد Entitlements التي تريد تسليمها عند شراء المنتج. يمكن لمنتج واحد تسليم عدة Entitlements في الوقت نفسه. على سبيل المثال، يمكن أن تتضمن خطة Pro مفتاح ترخيص وإمكانية وصول إلى GitHub ودورًا في Discord.
Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.
بعد الشراء، يتلقى العميل رسالة تسليم إلكترونية تتضمن مفتاح الترخيص أو روابط التنزيل أو روابط دعوة OAuth أو دعوة المنصة التي تنطبق على Entitlements الموجودة في المنتج. وتظل التفاصيل نفسها متاحة في Customer Portal، ضمن سجل الطلبات، ما دام Grant نشطًا.
يتطلب وصول المشتركين إلى Discord وGitHub وNotion أن يسمح العميل لـ Dodo Payments بمنح هذا الوصول. تبقى هذه Grants في الحالة Pending إلى أن يكمل العميل تدفق OAuth من الرابط الموجود في بريده الإلكتروني أو في Customer Portal. بعد منح العميل الموافقة، ينتقل Grant إلى Delivered ويجهّز Dodo Payments إمكانية الوصول إلى المنصة.
عند إبطال Grant، يزيل Dodo Payments إمكانية الوصول من المنصة: إذ يزيل دور Discord أو يزيل متعاون GitHub أو يعطّل مفتاح الترخيص. ويرى العميل التغيير في Customer Portal.
بالنسبة إلى Digital Files، يمنع الإبطال إنشاء روابط تنزيل موقعة مسبقًا جديدة، لكنه لا يبطل النسخ التي نزّلها العميل بالفعل. خطط للتحكم في الوصول إلى محتواك مع مراعاة ذلك.
افتح أي 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 entitlementconst grants = await client.entitlements.grants.list('ent_abc123', { status: 'Delivered',});// Revoke a single grantawait client.entitlements.grants.revoke('entg_xyz789', { id: 'ent_abc123',});
يرسل 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 واحدًا لكل قناة تسليم. لا تشارك 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.
