توصيل المنتجات الرقمية

نظرة عامة

توصيل المنتجات الرقمية هو نوع الاستحقاق Digital Files. تحمّل ملفاتك مرة واحدة إلى استحقاق Digital Files، وتربط الاستحقاق بمنتج، ثم يسلّم Dodo Payments روابط تنزيل موقعة مسبقًا إلى كل عميل دفع عبر البريد الإلكتروني وبوابة العميل. يدعم الاستحقاق ما يلي:

تحميلات الملفات المستضافة: خزّن الملفات على Dodo Payments وقدّمها عبر روابط موقعة مسبقًا قصيرة الأجل.
روابط التنزيل الخارجية: اربط بالملفات المستضافة على Dropbox أو Google Drive أو S3 أو أي عنوان URL.
تعليمات التنزيل: نص حر يظهر للعميل في صفحة الطلب وفي رسالة التسليم الإلكترونية.

يمكنك دمج الأنواع الثلاثة كلها في استحقاق واحد.

الميزات الرئيسية

File Upload

حمّل ملفات (PDF وZIP وصور وفيديوهات وغير ذلك) يصل حجمها إلى 500 MiB. تُبث الملفات وتُخزّن بكفاءة.

Multiple Files

أرفق أي عدد تحتاج إليه من الملفات باستحقاق واحد.

External Links

وفّر روابط تنزيل خارجية (Dropbox وGoogle Drive وروابط S3 موقعة) كبديل أو إضافة.

Presigned URLs

تُقدّم الملفات المستضافة عبر روابط موقعة مسبقًا قصيرة الأجل. تنتهي صلاحية كل رابط تنزيل تلقائيًا بعد نحو 15 دقيقة.

إعداد توصيل المنتجات الرقمية

Open Entitlements

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

Choose Digital Files

حدّد Digital Product Delivery باعتباره التكامل.

Add files, links, and instructions

اضبط أي مجموعة من الخيارات التالية:

Files: حمّل ملفًا واحدًا أو أكثر. يعيد كل تحميل file_id تتم إضافته إلى الاستحقاق.
External URL: رابط HTTPS يمكن الوصول إليه بشكل عام، ويتم تسليمه إلى جانب الملفات المستضافة.
Instructions: نص حر يظهر للعميل (مثل: “فك الضغط وشغّل setup.sh”).

استحقاق Digital Files مع حقول تحميل الملفات وعنوان URL خارجي والتعليمات

Save the entitlement

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

الإرفاق بالمنتجات

افتح منتجًا، ووسّع Advanced Settings → Entitlements & Credits، ثم حدّد استحقاق Digital Files. يُسلّم الاستحقاق عند كل عملية شراء ناجحة أو اشتراك نشط مرتبط بذلك المنتج.

لوحة استحقاقات المنتج تعرض تحديد Digital Product Delivery — Attaching the Digital Files entitlement to a product alongside other entitlements.

آلية التسليم

يتبع تسليم Digital Files دورة حياة المنح القياسية:

الحدث	السلوك
`payment.succeeded` (مرة واحدة)	إصدار منحة. تحتوي المنحة على روابط تنزيل موقعة مسبقًا صالحة لنحو 15 دقيقة؛ ويمكن للعملاء تحديثها بإعادة فتح رابط البريد الإلكتروني أو صفحة بوابة العميل.
`subscription.active`	إصدار منحة. تظل الملفات متاحة ما دام الاشتراك نشطًا.
`subscription.renewed`	لا عملية. تستمر المنحة نفسها؛ وتُنشأ روابط موقعة مسبقًا جديدة عند كل جلب.
`subscription.on_hold` / `cancelled` / `expired`	إلغاء المنحة. لن تُصدر روابط موقعة مسبقًا جديدة.
`subscription.plan_changed`	إلغاء المنحة القديمة وإصدار منحة جديدة للخطة الجديدة واستحقاقها.
`refund.succeeded` (مرة واحدة)	إلغاء المنحة.
الإلغاء اليدوي	الإلغاء باستخدام `revocation_reason: manual`.

يمنع الإلغاءُ Dodo Payments من إصدار روابط تنزيل جديدة، لكنه لا يبطل النسخ التي نزّلها العميل بالفعل. تعامل مع تنزيلات الملفات المستضافة على أنها “تُسلّم بمجرد قراءتها”.

تجربة العميل

تأكيد الشراء

بعد إتمام معاملة ناجحة، يتلقى العميل رسالة إلكترونية تحتوي على روابط التنزيل وأي تعليمات قمت بإعدادها.

الوصول عبر Customer Portal

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

واجهة بوابة العميل تعرض المنتجات الرقمية المتاحة للتنزيل

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

إدارة الملفات برمجيًا

تحميل ملف إلى استحقاق

import DodoPayments from 'dodopayments';
import fs from 'node:fs';

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

await client.entitlements.files.upload('ent_files_abc', {
  file: fs.createReadStream('./pro-bundle.zip'),
  filename: 'pro-bundle.zip',
});

curl -X POST "https://test.dodopayments.com/entitlements/ent_files_abc/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./pro-bundle.zip" \
  -F "filename=pro-bundle.zip"

سرد المنح وحل روابط التنزيل

const grants = await client.entitlements.grants.list('ent_files_abc', {
  customer_id: 'cus_abc123',
});

for (const grant of grants.items) {
  for (const file of grant.digital_product_delivery.files) {
    console.log(file.filename, file.download_url, `expires in ${file.expires_in}s`);
  }
}

إزالة ملف من استحقاق

await client.entitlements.files.delete('df_a4f6c1de', { id: 'ent_files_abc' });

اعتبارات مهمة

تنتهي صلاحية الروابط الموقعة مسبقًا بسرعة. روابط التنزيل المعادة في حمولات المنح أو أحداث webhook صالحة لنحو 15 دقيقة. لا تخزّنها؛ أعد جلبها عندما يحتاج العميل إلى التنزيل مرة أخرى.
يؤثر تحديث الملفات في عمليات الشراء المستقبلية فقط. لا يؤدي استبدال ملف أو إزالته إلى تغيير التنزيلات التي أُصدرت سابقًا بأثر رجعي. ولا يزال بإمكان العملاء السابقين إعادة جلب الإصدار الذي كان ساريًا عند إنشاء منحهم.
لا تُبطل عمليات رد الأموال النسخ التي تم تنزيلها. يحتفظ العميل الذي نزّل ملفًا بالفعل بنسخته. بالنسبة إلى المحتوى القابل للإلغاء (الوسائط المقيدة بترخيص، والوصول المحدد زمنيًا)، اقرن Digital Files بـ License Keys وأجرِ التحقق أثناء التشغيل.
للمحتوى الحساس، يُفضّل استخدام عناوين URL خارجية مع المصادقة الخاصة بها. روابط Dodo Payments الموقعة مسبقًا قصيرة الأجل لكنها غير موثّقة خلال فترة صلاحيتها؛ ويمكن لأي شخص يملك الرابط التنزيل خلال تلك الفترة. يوفر المحتوى المستضاف خارجيًا والمقيّد بحسابات ضمانات أقوى.

إدارة API

Create Entitlement

أنشئ استحقاق Digital Files مع عنوان URL خارجي وتعليمات اختياريين.

Upload File

حمّل ملفًا (بحد أقصى 500 MiB) وأضِفه إلى الاستحقاق.

Delete File

أزل ملفًا من الاستحقاق.

List Grants

اسرد المنح واقرأ روابط التنزيل التي تم حلها.

Update Entitlement

حدّث التعليمات أو العنوان URL الخارجي، أو استبدل الملفات.

Revoke Grant

ألغِ وصول العميل يدويًا.

Webhooks

يُطلق تسليم الملفات الرقمية وإلغاؤها أحداث webhook الأربعة المدرجة في أحداث webhook الخاصة بـ entitlement_grant.*. بالنسبة إلى منح Digital Files، تتضمن الحمولة كائن digital_product_delivery مع قائمة الملفات التي تم حلها (الروابط الموقعة مسبقًا وأسماء الملفات وأحجامها)، وinstructions الاختياري، وexternal_url الاختياري.

"digital_product_delivery": {
  "files": [
    {
      "file_id": "df_a4f6c1de",
      "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
      "filename": "pro-bundle.zip",
      "content_type": "application/zip",
      "file_size": 18742390,
      "expires_in": 900
    }
  ],
  "instructions": "Unzip and run setup.sh from the project root.",
  "external_url": null
}