Skip to main content
لكي يكتب وكيل البرمجة لديك التكامل، ثبّت Dodo Agent Plugin. يضيف هذا المكوّن مهارات Dodo Payments وخوادم MCP إلى Claude Code وCodex CLI وCursor وVS Code / GitHub Copilot وKiro وOpenCode.
ستنشئ MailKit، وهي خدمة بريد إلكتروني للمعاملات يشتري فيها العملاء أرصدة البريد الإلكتروني مسبقًا. تمنح الخطة الشهرية 5,000 رسالة بريد إلكتروني في كل دورة فوترة. وعندما يوشك رصيد العميل على النفاد، يشتري حزمة إعادة تعبئة بدلًا من الانتظار حتى الدورة التالية. يُخصم رصيد واحد مع كل إرسال.
يستخدم هذا البرنامج التعليمي Resend كمزوّد للبريد الإلكتروني. تغطي طبقته المجانية (3,000 رسالة بريد إلكتروني شهريًا) عملية الإنشاء والاختبار بالكامل. يعمل نمط الفوترة مع أي مزوّد: استبدل resend.emails.send باستدعاء إلى SendGrid أو Postmark أو Amazon SES أو مرحّل SMTP الخاص بك.
عند الانتهاء، ستعرف كيفية تنفيذ ما يلي:
  • إنشاء استحقاق أرصدة مخصّص للبريد الإلكتروني في لوحة التحكم.
  • إرفاق الأرصدة بخطة اشتراك وبمنتج إعادة تعبئة يُشترى لمرة واحدة.
  • إرسال البريد الإلكتروني عبر Resend وخصم رصيد واحد لكل إرسال مع إدخال في دفتر الأستاذ.
  • قراءة رصيد أرصدة العميل الحالي من الواجهة الأمامية.
  • التحقق من Webhooks الخاصة بـ Dodo Payments ومعالجة credit.balance_low لتحذير العملاء قبل وصول رصيدهم إلى الصفر.

ما سنبنيه

تبيع MailKit منتجين: الوحدة هي رسالة بريد إلكتروني واحدة = رصيد واحد. لا يحتاج العملاء إلى التفكير في الرموز أو الدُفعات أو الوحدات الموزونة. سيظهر لهم “تبقى 4,231 رسالة بريد إلكتروني هذا الشهر.” قبل البدء، تحتاج إلى ما يلي:
  • حساب Dodo Payments. أنشئ كل شيء في وضع الاختبار.
  • حساب Resend مجاني ومفتاح API.
  • Node.js 22 أو إصدار أحدث، ومعرفة عملية بـ TypeScript.

الخطوة 1: إنشاء استحقاق أرصدة البريد الإلكتروني

يحدد استحقاق الأرصدة الوحدة التي تبيعها MailKit: إرسال رسالة بريد إلكتروني واحدة.
علامة تبويب الأرصدة ضمن المنتجات، وتعرض استحقاقات أرصدة النشاط التجاري

The Credits tab under Products lists all your credit entitlements.

1

Open the Credits Section

  1. سجّل الدخول إلى لوحة تحكم Dodo Payments.
  2. انقر على Products في الشريط الجانبي.
  3. حدّد علامة تبويب Credits.
  4. انقر على Create Credit.
2

Configure the Credit Unit

أدخل القيم التالية:اسم الرصيد: Email Creditsنوع الرصيد: وحدة مخصّصةاسم الوحدة: emailتحديد الدقة: 0. الرسالة الإلكترونية وحدة كاملة، لذلك لا يحتاج الرصيد إلى أرقام عشرية.انتهاء صلاحية الرصيد: 30 days. تنتهي صلاحية الأرصدة غير المستخدمة بعد 30 يومًا من إصدارها.
لا يمكن تغيير الدقة بعد إنشاء الرصيد. بالنسبة إلى الوحدات المنفصلة مثل رسائل البريد الإلكتروني أو الرسائل أو الجلسات، استخدم 0.
3

Leave the Other Defaults

يُبقي هذا البرنامج التعليمي الترحيل والزيادة خارج النطاق للحفاظ على بساطة تدفق الأرصدة. يمكنك تفعيلهما لاحقًا، إما على الرصيد أو على إرفاق أرصدة كل منتج.
4

Save and Copy the Credit ID

انقر على Create Credit. افتح الرصيد وانسخ معرّفه، الذي يبدأ بـ cde_. تستخدمه الواجهة الخلفية لقراءة الأرصدة وإدخالات دفتر الأستاذ.
أصبح استحقاق Email Credits جاهزًا. بعد ذلك، أنشئ المنتجات التي تمنحه للعملاء.

الخطوة 2: إنشاء الخطة وحزمة إعادة التعبئة

أنشئ منتجين يرفقان استحقاق Email Credits نفسه: خطة Subscription تمنح 5,000 رسالة بريد إلكتروني في كل دورة فوترة، ومنتج إعادة تعبئة One Time يضيف 5,000 رسالة أخرى عند الطلب.
يخصم هذا البرنامج التعليمي الأرصدة باستخدام إدخالات دفتر الأستاذ بدلًا من عدادات الاستخدام. يُطبّق خصم دفتر الأستاذ عند إرجاع استدعاء API، ولا يحتاج إلى إعداد عدّاد، ويناسب الحالات التي تكلّف فيها كل عملية مستخدم رصيدًا واحدًا بالضبط. لخصم الأرصدة تلقائيًا من أحداث الاستخدام المُدخلة، وهو ما يناسب الوحدات الموزونة مثل الرموز أو الميغابايتات المعالَجة، راجع Usage Billing with Credits في دليل Credit-Based Billing.

خطة MailKit ($19/شهريًا، 5,000 رسالة بريد إلكتروني)

1

Create the Subscription

  1. انتقل إلى Products وانقر على Add Product.
  2. أدخل تفاصيل المنتج:
اسم المنتج: MailKit Planالوصف: 5,000 transactional emails per month.
  1. ضمن Pricing Type، حدّد Subscription.
  2. حدّد السعر المتكرر:
السعر: 19.00تكرار الدفع كل: 1 شهرالعملة: USD
2

Attach the Email Credit Entitlement

في قسم Entitlements، انقر على Attach بجانب Credits واضبط ما يلي:حدّد الأرصدة: Email Creditsالأرصدة المُصدرة في كل دورة فوترة: 5000حد انخفاض الرصيد (%): 20. ترسل Dodo Payments credit.balance_low عندما ينخفض الرصيد عن 20% من الأرصدة المُصدرة في كل دورة، أي 1,000 رسالة بريد إلكتروني.استيراد إعدادات الرصيد الافتراضية: مفعّل، لكي يستخدم المنتج مدة الصلاحية البالغة 30 يومًا من الخطوة 1.أضف الرصيد إلى المنتج، ثم احفظ المنتج. انسخ معرّف المنتج، الذي يبدأ بـ pdt_.
الخطة: $19/شهريًا، مع إصدار 5,000 رسالة بريد إلكتروني في كل دورة فوترة.

حزمة إعادة التعبئة ($9 لمرة واحدة، 5,000 رسالة بريد إلكتروني)

1

Create a One-Time Product

  1. انتقل إلى Products وانقر على Add Product.
  2. أدخل تفاصيل المنتج:
اسم المنتج: Email Top-Up Packالوصف: Add 5,000 emails to your MailKit balance.
  1. ضمن Pricing Type، حدّد One Time.
  2. حدّد السعر:
السعر: 9.00العملة: USD
2

Attach the Credit Grant

في قسم Entitlements، انقر على Attach بجانب Credits واضبط ما يلي:
  • حدّد الأرصدة: Email Credits
  • عدد الأرصدة المُصدرة: 5000
يمنح المنتج الذي يُشترى لمرة واحدة أرصدة بمدة صلاحية خاصة بها: 30 يومًا من تاريخ الشراء، وفق الإعداد الافتراضي الذي حددته في الخطوة 1. تُضاف أرصدة إعادة التعبئة إلى أرصدة الاشتراك، ولا تستبدلها.
احفظ المنتج وانسخ معرّفه.
حزمة إعادة التعبئة: $9 مقابل 5,000 رسالة بريد إلكتروني، تُضاف إلى الرصيد بعد نجاح الدفع.

الخطوة 3: إعداد الواجهة الخلفية

أنشئ خادم Express الذي ينشئ عمليات الدفع، ويرسل البريد الإلكتروني، ويقرأ الأرصدة، ويستقبل Webhooks.
1

Initialize the Project

أضف برنامجًا نصيًا للتطوير إلى package.json:
يُشغّل tsx TypeScript مباشرةً، من دون خطوة بناء أو tsconfig.json. في بيئة الإنتاج، أضف tsconfig.json وبرنامجًا نصيًا build.
2

Configure Environment Variables

أنشئ .env باستخدام مفتاح API لوضع الاختبار من Developer → API Keys، ومعرّفات الخطوتين 1 و2:
.env
ستملأ DODO_PAYMENTS_WEBHOOK_KEY في الخطوة 4، بعد إنشاء نقطة نهاية Webhook. أنشئ مفتاح Resend API من resend.com/api-keys.
أضف .env إلى .gitignore قبل أول commit. لا تُودع مفاتيح API أبدًا.
3

Build the Server

أنشئ server.ts في جذر المشروع. يوفّر الخادم خمسة مسارات: الدفع للاشتراك، والدفع لإعادة التعبئة، وقراءة الرصيد، والإرسال، ومستقبل Webhook.
يجب أن يستقبل مسار Webhook نص الطلب الخام. يستبدل express.json() النص بكائن محلّل، ويتطلب التحقق من التوقيع البايتات الدقيقة التي وقّعتها Dodo Payments. أبقِ مسار /webhooks/dodo، مع express.raw()، أعلى سطر app.use(express.json()).
أصبحت الواجهة الخلفية جاهزة: الاشتراك، وإعادة التعبئة، والرصيد، والإرسال، ومعالج Webhook.
4

Add a Demo UI

أنشئ public/index.html. يستدعي كل مسار من نموذج بسيط، بحيث يمكنك اختبار التدفق في متصفح:

الخطوة 4: ربط نقطة نهاية Webhook

يتيح لك حدث credit.balance_low تحذير العملاء قبل نفاد أرصدتهم. ومن دونه، يلاحظ العميل المشكلة أولًا عند فشل إرسال رسالة بريد إلكتروني.
1

Expose Your Local Server

تحتاج Webhooks إلى عنوان URL عام. أثناء التطوير، استخدم ngrok أو نفقًا آخر:
انسخ عنوان URL لإعادة التوجيه عبر HTTPS، مثل https://1234abcd.ngrok-free.app.
2

Register the Endpoint in Dodo Payments

  1. انتقل إلى Developer → Webhooks وانقر على Add endpoint.
  2. أدخل عنوان URL https://1234abcd.ngrok-free.app/webhooks/dodo، باستخدام مضيف النفق الخاص بك.
  3. حدّد الأحداث credit.added وcredit.balance_low وcredit.rolled_over.
  4. انقر على Create endpoint.
  5. انسخ سر التوقيع من علامة تبويب Overview لنقطة النهاية إلى .env على هيئة DODO_PAYMENTS_WEBHOOK_KEY.
  6. أعد تشغيل الخادم.

الخطوة 5: اختبار التدفق بالكامل

1

Start the Server

يسجل الخادم MailKit running on http://localhost:3000. افتح عنوان URL هذا في متصفحك.
2

Subscribe a Test Customer

  1. في القسم 1، أدخل عنوان بريد إلكتروني واسمًا للاختبار، ثم انقر على Get checkout link.
  2. افتح الرابط وأكمل الدفع باستخدام بطاقة اختبار.
  3. في لوحة التحكم، انتقل إلى Customers وانسخ معرّف العميل الجديد، الذي يبدأ بـ cus_.
لدى العميل 5,000 رسالة بريد إلكتروني في رصيده. للتأكد، افتح العميل ضمن Customers وحدّد علامة تبويب Credits.
3

Send an Email

  1. ألصق معرّف العميل في القسم 3.
  2. اترك To مضبوطًا على delivered@resend.dev، وهو عنوان اختبار في Resend يقبل كل رسالة.
  3. انقر على Send.
تعرض الصفحة معرّف رسالة Resend. حدّث الرصيد في القسم 2: سيظهر 4,999. يصبح خصم دفتر الأستاذ جزءًا من الرصيد بمجرد إرجاع استدعاء API.
4

Trigger the Low-Balance Webhook

الحد هو 20%، أي 1,000 من أصل 5,000 رسالة بريد إلكتروني مُصدرة في كل دورة. للوصول إليه من دون إرسال 4,000 رسالة، اخصم الرصيد يدويًا في لوحة التحكم:
  1. افتح العميل ضمن Customers، وحدّد علامة تبويب Credits، واختر Email Credits.
  2. انقر على Apply Credit/Debit، وحدّد Debit، وأدخل 4000. أصبح الرصيد الآن 1,000 بالضبط، وهو ليس أقل من الحد بعد.
  3. أرسل رسالة بريد إلكتروني أخرى من العرض التجريبي. ينخفض الرصيد إلى 999.
عند وصول Webhook، يسجل الخادم:
استقبل الخادم Webhook وتحقق منه. في بيئة الإنتاج، هذا هو الموضع الذي ترسل فيه بريدًا إلكترونيًا إلى العميل أو تعرض فيه لافتة داخل التطبيق.
5

Buy a Top-Up Pack

  1. ألصق معرّف العميل في القسم 4.
  2. انقر على Buy 5,000 emails وأكمل عملية الدفع الاختبارية.
  3. حدّث الرصيد. سيزداد بمقدار 5,000.
ترسل Dodo Payments حدث credit.added مع transaction_type: "credit_added". يحتوي الاستحقاق المرتبط به على source_type: one_time، ويمكنك قراءته مجددًا باستخدام API ‏List Customer Grants. تُضاف أرصدة إعادة التعبئة إلى أرصدة الاشتراك. تُخصم الدفعات من الاستحقاق الذي تنتهي صلاحيته أولًا، ومن أقدم استحقاق عندما تنتهي صلاحية استحقاقين في الوقت نفسه.
6

Test the Hard Stop

اخفض الرصيد إلى الصفر في لوحة التحكم، ثم حاول إرسال رسالة بريد إلكتروني أخرى. يستجيب الخادم بـ 402:
يمثل 402 آلية الإنفاذ في تطبيقك. اعتبر API رصيد Dodo Payments مصدر الحقيقة، ولا تخزّن الرصيد مؤقتًا في العميل.

استكشاف الأخطاء وإصلاحها

يغطي التوقيع نص HTTP الخام. يستبدل express.json() النص بكائن محلّل، ولذلك يفشل التحقق. سجّل /webhooks/dodo باستخدام express.raw({ type: 'application/json' }) أعلى سطر app.use(express.json()). ثم تحقق من أن DODO_PAYMENTS_WEBHOOK_KEY يطابق سر التوقيع في علامة تبويب Overview لنقطة النهاية.
تحقق من هذه الأمور الثلاثة بالترتيب:
  1. أن العميل أكمل عملية الدفع. تُصدر الأرصدة عند نجاح الدفع، وليس عند إنشاء جلسة الدفع.
  2. أن CREDIT_ENTITLEMENT_ID في .env يطابق الرصيد المرفق بالمنتج. تستخدم استدعاءات الرصيد ودفتر الأستاذ هذا المعرّف، لذا تؤدي عدم المطابقة إلى قراءة رصيد مختلف أو خصمه.
  3. أن customer_id الذي تمرره هو معرّف عميل Dodo Payments (يبدأ بـ cus_)، وليس معرّفًا من قاعدة بياناتك الخاصة.
لا يرسل المُرسِل الاختباري onboarding@resend.dev إلا إلى عنوان البريد الإلكتروني الموجود في حساب Resend الخاص بك، أو إلى delivered@resend.dev. للإرسال إلى أي شخص آخر، تحقق من نطاق واستخدم عنوان from على ذلك النطاق.

ما أنشأته

One Reusable Credit Unit

Email Credits، عُرّف مرة واحدة وأُرفق بكل من خطة الاشتراك وحزمة إعادة التعبئة.

Subscription with Prepaid Allowance

تمنح $19/شهريًا 5,000 رسالة بريد إلكتروني في كل دورة فوترة. يعرف العملاء ما يدفعون مقابله، وتعرف أنت الحد الأقصى لتكلفتك.

Top-Up Pack

منتج يُشترى لمرة واحدة يمنح 5,000 رسالة بريد إلكتروني بالإضافة إلى أرصدة الاشتراك، من دون تغيير الخطة.

Direct Ledger Debits

استدعاء واحد لـ createLedgerEntry بعد كل إرسال، من دون عدّاد أو تأخير في التجميع. يمنع معرّف رسالة Resend باعتباره مفتاح idempotency خصمًا ثانيًا للإرسال نفسه.

Credit-Based Billing Reference

الترحيل، وأنماط الزيادة، وإدارة دفتر الأستاذ، وCredit API الكامل.
للحصول على المساعدة، اطرح سؤالك في مجتمع Discord أو أرسل بريدًا إلكترونيًا إلى support@dodopayments.com.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦