- إنشاء استحقاق رصيد مخصص (رموز) وعداد يخصم منه تلقائيًا
- إرفاق الأرصدة بخطط الاشتراك (مع الاستخدام الزائد وبدونه) وبمنتج شحن لمرة واحدة
- ربط نقطة نهاية completion حقيقية من OpenAI تفوتر الرموز عبر Dodo Payments
- الاستعلام عن رصيد الأرصدة المباشر للعميل عبر SDK
- التحقق من تواقيع webhooks وتوجيه أحداث الأرصدة الخاصة بـ Dodo Payments
ما الذي سنبنيه
إليك نموذج التسعير الخاص بـ NeuralAPI:- حساب Dodo Payments (يكفي وضع الاختبار)
- مفتاح OpenAI API
- Node.js 18+
- معرفة أساسية بـ TypeScript/Node.js
الخطوة 1: إنشاء استحقاق رصيد الرموز
أولًا، أنشئ استحقاق الرصيد الذي ستشترك فيه خطتا الاشتراك وحزمة الشحن. فكّر فيه على أنه تعريف لوحدة “الرمز” التي تستخدمها منصتك.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- سجّل الدخول إلى لوحة تحكم Dodo Payments
- انقر على Products في الشريط الجانبي الأيسر
- اختر علامة تبويب Credits
- انقر على Create Credit
Configure the credit unit
API Tokensنوع الرصيد: اختر Custom Unitاسم الوحدة: tokenالدقة: 0 (الرموز دائمًا أعداد صحيحة)انتهاء صلاحية الرصيد: 30 days (تُعاد تهيئة الأرصدة في كل دورة فوترة)Skip overage at the credit level
Save and copy the credit ID
cent_xxxxxxxxxxxx.API Tokens جاهزًا. بعد ذلك، أنشئ عدادًا حتى تتمكن أحداث الاستخدام من تشغيل الخصومات تلقائيًا.الخطوة 2: إنشاء عداد لاستخدام الرموز
يجمع العداد أحداث الاستخدام الواردة ويحوّلها إلى خصومات من الأرصدة. تحتاج إليه قبل إنشاء منتجات الخطط، إذ ستُرفقه أثناء إنشاء المنتجات في الخطوة 3.Open the Meters section
- في الشريط الجانبي للوحة التحكم، انتقل إلى Products ← Meters
- انقر على Create Meter
Configure the meter
Token Usage Meterاسم الحدث: api.tokens_used (يجب أن يطابق تمامًا ما يرسله تطبيقك)نوع التجميع: Sum — نجمع عدد الرموز من كل حدثالخاصية: tokens — مفتاح البيانات الوصفية في كل حدث الذي ستُجمع قيمتهوحدة القياس: tokensاحفظ العداد وانسخ معرّفه — ستشير إليه عند إرفاقه بالمنتجات.الخطوة 3: إنشاء منتجات الخطط
يجب أن يكون كلا المنتجين من نوع Usage Based Billing، وليس Subscription عاديًا — فلا يمكن إرفاق العدادات إلا بمنتجات UBB، وأنت تحتاج إلى العداد لخصم الأرصدة تلقائيًا أثناء استدعاء العملاء لواجهة API الخاصة بك. ما تزال منتجات UBB تدعم رسمًا أساسيًا متكررًا ($29 / $99)؛ وتُفوتر الاستخدامات الإضافية بالأرصدة.

Usage Based Billing pricing type with meter configuration.
خطة Starter (29 دولارًا/شهريًا — 10M رمز، دون استخدام زائد)
Create the Starter UBB product
- انتقل إلى Products → Create Product
- اختر Usage Based Billing كنوع التسعير
- أدخل ما يلي:
NeuralAPI Starterالوصف: 10 million API tokens per month. Perfect for individual developers and small projects.السعر الثابت: 29.00 (الرسم الأساسي المتكرر — يُفوتر شهريًا حتى قبل وجود أي استخدام)دورة الفوترة: Monthlyالعملة: USDAttach the meter
Token Usage Meter. ثم في العداد:- فعّل Bill usage in Credits
- استحقاق الرصيد: اختر
API Tokens - وحدات العداد لكل رصيد:
1— يطابق كل رمز في الحدث رصيدًا واحدًا مخصومًا - الحد المجاني:
0— يُعد تخصيص الرصيد نفسه “المستوى المجاني” للعميل؛ ولا نحتاج إلى نطاق مجاني إضافي

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used الواردة تخصم فعليًا من رصيد العميل.Configure credit issuance for Starter
10000000السماح بالاستخدام الزائد: معطل — يُحظر عملاء Starter عند نفاد الرموزاستيراد إعدادات الرصيد الافتراضية: مفعّل — استخدم انتهاء الصلاحية بعد 30 يومًا من استحقاق الرصيد
Configure credit issuance per cycle on the UBB product.
خطة Pro (99 دولارًا/شهريًا — 40M رمز، الاستخدام الزائد مفعّل)
Create the Pro UBB product
NeuralAPI Proالوصف: 40 million API tokens per month with overage. Built for production applications.السعر الثابت: 99.00دورة الفوترة: Monthlyالعملة: USDAttach the meter
Token Usage Meter، وفعّل Bill usage in Credits، واختر API Tokens، واضبط وحدات العداد لكل رصيد على 1، والحد المجاني على 0.Configure credit issuance with overage
40000000استيراد إعدادات الرصيد الافتراضية: معطل — نحتاج إلى تخصيص إعدادات الاستخدام الزائد لكل منتجالسماح بالاستخدام الزائد: مفعّلالسعر لكل وحدة: 0.000005 دولار لكل رمز (أي 0.005 دولار لكل 1K رمز، أو 5 دولارات لكل 1M رمز — أعلى من معدل الخطة الفعلي لكل رمز للحد من التجاوز)سلوك الاستخدام الزائد: Bill overage at billing — يُفرض رسم الاستخدام الزائد في الفاتورة التالية، ثم يُعاد ضبط الرصيداحفظ المنتج وانسخ معرّفه.الخطوة 4: إنشاء حزمة شحن الرموز
حزمة الشحن هي عملية شراء لمرة واحدة تمنح 5,000,000 رمز إلى رصيد عميل موجود.
Single Payment pricing selected for a one-time credit product.
Create a one-time product
- انتقل إلى Products → Create Product
- اختر Single Payment كنوع التسعير
- أدخل ما يلي:
Token Top-Up Packالوصف: Instantly add 5 million tokens to your NeuralAPI balance.السعر: 19.00العملة: USDAttach the token credit
- في قسم Entitlements، انقر على Attach بجوار Credits
- اختر
API Tokens - اضبط الأرصدة المُصدرة على:
5000000 - عطّل Import Default Credit Settings — نريد تجاوز انتهاء الصلاحية الافتراضي بعد 30 يومًا
- اضبط انتهاء صلاحية الرصيد على:
365 days - احفظ المنتج
الخطوة 5: إنشاء النظام الخلفي
لننشئ الآن خادم Express الذي يتعامل مع إتمام الاشتراك، وإتمام شراء الشحن، وعمليات completion الحقيقية من OpenAI مع فوترة الرموز، والاستعلامات عن الرصيد، وأحداث webhooks الخاصة بالأرصدة.Set up your project
tsconfig.json:package.json:Set up environment variables
.env باستخدام بيانات الاعتماد والمعرّفات من الخطوات السابقة:DODO_PAYMENTS_WEBHOOK_KEY في الخطوة 7 بعد تسجيل نقطة نهاية webhook الخاصة بك.Implement the server
src/server.ts:A note on how deductions actually happen
- يستدعي معالجك OpenAI ويحصل على
usage.total_tokens(مثلًا، 1532). - تُدخل حدث استخدام واحدًا:
event_name: api.tokens_used،metadata: { tokens: 1532 }. - يجمع
Token Usage Meterالأحداث حسب العميل. - لأن العداد مرتبط برصيد
API Tokensمع تفعيل Bill usage in Credits، تخصم Dodo Payments 1532 رصيدًا من أقدم منحة غير منتهية الصلاحية للعميل (FIFO). - إذا كان الاستخدام الزائد مفعّلًا وانخفض العميل إلى ما دون الصفر، يُتتبّع العجز وتُفرض تكلفته في الفاتورة التالية.
الخطوة 6: إضافة واجهة أمامية تجريبية
أنشئpublic/index.html لاختبار جميع التدفقات في متصفحك. نحتفظ بمعرّف العميل في localStorage حتى تشترك → تنشئ → تشحن باستخدام الهوية نفسها، لمحاكاة تطبيق سجّل المستخدم الدخول إليه:
الخطوة 7: ربط webhook
تتيح webhooks لخادمك التفاعل مع تغييرات الرصيد — وستستخدمها لإرسال رسائل بريد إلكتروني تفيد بأن الرصيد “ينخفض” قبل وصول العملاء إلى الصفر.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- في لوحة التحكم، انتقل إلى Developers → Webhooks → Add Endpoint
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - اشترك في الأحداث التالية (كحد أدنى):
credit.addedcredit.deductedcredit.overage_charged
- احفظ وانسخ Signing Secret
- الصقه في
.envبوصفهDODO_PAYMENTS_WEBHOOK_KEY، ثم أعد تشغيلnpm run dev
الخطوة 8: اختبار التدفق الكامل
Subscribe a test customer
- شغّل
npm run dev - افتح
http://localhost:3000 - اختر خطة Pro، وأدخل بريدًا إلكترونيًا واسمًا للاختبار، وانقر على Get Checkout Link، وأكمل الدفع باستخدام بيانات بطاقة الاختبار
- في لوحة التحكم، انتقل إلى Customers → most recent وانسخ معرّف
cus_... - الصقه في حقل “معرّف العميل الذي سجّل الدخول” في العرض التجريبي وانقر على Save
Generate a real AI response
total_tokens الفعلي، ويدخل حدث استخدام، ثم يعيد الاستجابة.Test the top-up flow
credit.added.استكشاف الأخطاء وإصلاحها
Credits not deducting after usage events
Credits not deducting after usage events
- لا يطابق اسم حدث العداد
event_nameالذي ترسله (api.tokens_usedحساس لحالة الأحرف) - العداد غير مرتبط برصيد
API Tokensفي المنتج — انتقل إلى إعدادات عداد المنتج وتأكد من تفعيل Bill usage in Credits - لا يطابق مفتاح
metadata.tokensحقل “Over Property” في العداد - انتهت صلاحية منحة العميل (تحقق من سجل أرصدة العميل)
- Products → Meters: افتح العداد وتأكد من ظهور اسم الرصيد المرتبط في إرفاق المنتج
- علامة تبويب Events في العداد — يجب أن تظهر الأحداث المُدخلة هناك حتى قبل الخصم
- Customers → [Customer] → Credits: يجب أن تظهر إدخالات السجل خلال دقيقة أو دقيقتين
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- لم يُكمل العميل عملية الدفع بعد — لا تُصدر الأرصدة إلا بعد نجاح الدفع
- تستعلم باستخدام
customer_idغير صحيح (استخدم معرّفcus_...من لوحة التحكم، وليس معرّف قاعدة بياناتك) - لا يطابق
CREDIT_ENTITLEMENT_IDفي.envالرصيد المرفق بالمنتج
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- لم يُفعّل الاستخدام الزائد في إرفاق رصيد منتج Pro (إعداد مستوى الرصيد ليس سوى إعداد افتراضي)
- العميل مشترك فعليًا في Starter وليس Pro
- تم ضبط حد الاستخدام الزائد على 0
0.000005 (= 5 دولارات لكل مليون رمز؛ تحقق مرة أخرى من الأصفار البادئة — فالحقل يقبل سعر كل رمز، وليس سعر كل 1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- ترتيب تحليل النص: تم تطبيق
express.json()على/webhooks/dodoقبلexpress.raw()— يحتاج SDK إلى البايتات الخام للطلب، وليس JSON الذي تم تحليله - سر التوقيع في
DODO_PAYMENTS_WEBHOOK_KEYغير صحيح - الوكيل العكسي يعيد كتابة الرؤوس
app.use('/webhooks/dodo', express.raw(...)) يأتي قبل app.use(express.json()) في server.ts.هل تحتاج إلى مساعدة؟
تهانينا! لقد أنشأت فوترة قائمة على الرصيد لـ NeuralAPI
تحتوي منصتك الآن على نظام فوترة كامل وجاهز للإنتاج قائم على الرصيد:Token Credit Entitlement
API Tokens قابل لإعادة الاستخدام، بانتهاء صلاحية بعد 30 يومًا، ومشترك بين جميع الخطط وحزمة الشحنTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added وcredit.deducted وcredit.overage_charged) موجّهة عبر معالج تم التحقق من توقيعه باستخدام مساعد Standard Webhooks في SDK- المصادقة على
/credits/:customerIdو/api/generate— يمكن لأي شخص حاليًا استدعاؤهما باستخدام أي معرّف عميل. صادِق على المستخدمين وابحث عن معرّف عميلهم على الخادم. event_ids ثابتة — يستخدم المثالDate.now() + random. في الإنتاج، استخدم معرّف طلبك حتى تكون عمليات إعادة المحاولة غير متكررة (Dodo Payments يزيل التكرارات حسبevent_id).- حفظ الربط بين العميل والمستخدم — خزّن
customer_idفي قاعدة بياناتك بعد أول عملية دفع حتى لا تحتاج إلى خطوة اللصق اليدوية. - حدّد ما يحدث عند انتهاء الاشتراك. تبقى أرصدة الخطة في سجل العميل حتى انتهاء صلاحيتها الطبيعي (30 يومًا من الإصدار)، وتظل أرصدة الشحن صالحة لمدة 365 يومًا — لكن
/api/generateفي cookbook يتحقق من الرصيد فقط، وليس من حالة الاشتراك. لذلك قد يواصل العميل الملغى استهلاك رموزه المتبقية. هذا هو الإعداد الافتراضي الملائم للمستهلك. إذا أردت تحكمًا أكثر صرامة في الوصول، فإما (أ) استمع إلى webhooksubscription.cancelledوتحكم في/api/generateبناءً على حالة الاشتراك، أو (ب) استدعِ API السجل الخاص بـ Dodo لخصم أرصدة الخطة غير المستخدمة عند الإلغاء مع إبقاء أرصدة الشحن كما هي. - راقب لوحة Usage Billing لاكتشاف الحالات الشاذة في القياس مبكرًا.