الانتقال إلى المحتوى الرئيسي

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، قالب في Notion، رابط Framer remix، دعوة دردشة Telegram، أو حزمة ملفات قابلة للتنزيل. تقوم Dodo Payments بإصدار هذا الوصول، تتبعه، وتلغيه تلقائيًا مع تغيير دورة حياة الدفع.
لوحة معلومات الاستحقاقات مع قائمة بالاستحقاقات على اليسار ونشاط المنح على اليمين

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

الاستحقاق هو تعريف قابل لإعادة الاستخدام لشيء تقدمه للعميل: مفتاح ترخيص Pro، دور “Patrons” في Discord، الوصول إلى مستودع GitHub الخاص بك، أو حزمة كتب إلكترونية قابلة للتنزيل. تقوم بإرفاق الاستحقاقات بالمنتجات، وتتعامل Dodo Payments مع الباقي. عندما يشتري العميل المنتج، تنشئ Dodo Payments منحة، وهي إصدار استحقاق مخصص لذلك العميل. تمر المنح بعدة حالات: pending أثناء تقدم التسليم، delivered بمجرد أن يحصل العميل على الوصول، failed إذا لم يكتمل التسليم، و revoked عند سحب الوصول.
تتحكم الاستحقاقات في التنفيذ (هل لدى العميل وصول؟). تتحكم الأرصدة في الاستهلاك (كم يمكنهم استخدامه؟). يمكن إرفاق كلاهما بنفس المنتج. راجع الفوترة المعتمدة على الأرصدة للأرصدة.

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

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

License Keys

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

Digital Files

تسليم الملفات القابلة للتنزيل (الكتب الإلكترونية، القوالب، الوسائط) مع عناوين URL مسبقة التوقيع وتعليمات اختيارية.

Discord

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

GitHub

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

Telegram

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

Framer

إلغاء قفل رابط Framer template remix للعملاء الذين يدفعون.

Notion

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

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

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

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

1

Created

يتم إنشاء المنحة عند اكتمال الدفع أو عند اشتراك يصبح نشطًا. تقفز مفاتيح الترخيص مباشرة إلى delivered. تبدأ جميع عمليات الدمج الأخرى في pending. تتضمن التكاملات المعتمدة على OAuth (Discord، GitHub، Notion) oauth_url يجب على العميل زيارته لإكمال الموافقة. تقف التكاملات المباشرة مع المنصات (Telegram، Framer، Digital Files) في pending فقط لفترة وجيزة أثناء تجهيز التسليم، ثم تنتقل إلى delivered.
2

Delivered

بمجرد اكتمال التسليم (تم إنشاء مفتاح الترخيص، تم تعيين الدور، تم منح الوصول للمستودع، تم حل روابط الملفات، اكتملت OAuth)، تنتقل المنحة إلى delivered ويتم تعيين delivered_at.
3

Failed

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

Revoked

عند سحب الوصول (تم إلغاء الاشتراك، إصدار استرداد، أو إلغاء بواسطة التاجر)، تنتقل المنحة إلى revoked. يسجل الحقل revocation_reason المحفز.

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

الحدثالسلوك
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. لا تُعاد منحها تلقائيًا عند تجديد الاشتراك حتى يتم حل مشكلة النظام الأساسي الأساسي.
المنح الناتجة عن الاشتراك لا تتكرر لكل (entitlement, customer, subscription)؛ التجديدات وإعادة التفعيل لا تنشئ منحًا مكررة. المنح مرة واحدة لا تكرر لكل (entitlement, customer, payment).

​
إنشاء استحقاقك الأول

1

Open Entitlements

انتقل إلى الاستحقاقات في لوحة معلومات Dodo Payments وانقر على + لإنشاء استحقاق جديد.
2

Pick an integration

اختر نوع التكامل: مفتاح الترخيص، الملفات الرقمية، Discord، GitHub، Telegram، Framer، أو Notion. بالنسبة لتكاملات المنصة، قم بتوصيل حسابك أولاً إذا لم تكن قد قمت بذلك بالفعل.
3

Configure delivery

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

Save

احفظ الاستحقاق. يمكنك الآن إرفاقه بأي منتج.

​
إرفاق الاستحقاقات بالمنتجات

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

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

​
البريد الإلكتروني وتطبيق العميل

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

​
التسليم المعتمد على OAuth

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

​
الإلغاء

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

​
إدارة المنح

افتح أي استحقاق من لوحة التحكم لترى منحها. تعرض لوحة تفاصيل المنحة إجمالي المنح، وفلاتر الحالة، ومعلومات العميل، وتواريخ التسليم، وإجراء الإلغاء. يمكنك أيضًا إدارة المنح برمجيًا: 
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', {
  path_id: 'ent_abc123',
});

​
إدارة API

Create Entitlement

إنشاء استحقاق جديد من أي نوع تكامل.

List Entitlements

قائمة الاستحقاقات مع تصفية حسب نوع التكامل.

Get Entitlement

استرجاع الاستحقاق وتكوينه المحلول.

Update Entitlement

تحديث الاسم، الوصف، أو تكوين التكامل.

Delete Entitlement

حذف لطيف لاستحقاق؛ لا تتأثر المنح الحالية.

Upload File

تحميل ملف إلى استحقاق الملفات الرقمية (حتى 100 ميجابايت).

List Grants

قائمة بجميع المنح لاستحقاق مع فلاتر الحالة والعميل.

Revoke Grant

إلغاء يدوي لمنحة واحدة.

​
الإشعارات

تقوم Dodo Payments بإطلاق أربعة أحداث إشعار ويب لدورة حياة المنحة. اشترك في هذه الأحداث للحفاظ على تطبيقك متزامنًا مع ما يمكن لكل عميل الوصول إليه.
الحدثيحدث عندما
entitlement_grant.createdتم إنشاء منحة جديدة. تصل منح مفتاح الترخيص delivered؛ تصل كل عملية تكامل أخرى pending وتنتقل إلى delivered بمجرد نجاح استدعاء المنصة (أو، بالنسبة للتكاملات المعتمدة على OAuth، بمجرد موافقة العميل).
entitlement_grant.deliveredتنتقل المنحة إلى المسلمة. الآن لدى العميل وصول.
entitlement_grant.failedلم يمكن تسليم المنحة. تحقق من error_code و error_message.
entitlement_grant.revokedتم سحب الوصول. تحقق من revocation_reason.

Entitlement Grant Webhook Payloads

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

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

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