Skip to main content
دع Sentra يكتب رمز التكامل الخاص بك.
استخدم مساعد AI الخاص بنا في VS Code أو Cursor أو Windsurf لإنشاء رمز SDK/API ومعالجات webhooks ومنح الأرصدة والمزيد — بمجرد وصف ما تريده.
جرّب Sentra: تكامل مدعوم بالذكاء الاصطناعي →
في هذا البرنامج التعليمي، ستنشئ NeuralAPI — منصة AI متعددة المستويات تأتي فيها كل خطة اشتراك بسماح شهري من أرصدة الرموز، ويمكن للعملاء شراء حزم شحن عند انخفاض رصيدهم، ويقوم نظامك الخلفي تلقائيًا بخصم الأرصدة أثناء معالجة الطلبات بواسطة OpenAI.
يستخدم هذا البرنامج التعليمي Node.js/Express مع OpenAI SDK. تنطبق مفاهيم Dodo Payments (الأرصدة والعدادات وwebhooks) على أي إطار عمل أو مزود AI — ويمكنك تكييفها بحرية.
بنهاية هذا البرنامج التعليمي، ستعرف كيفية:
  • إنشاء استحقاق رصيد مخصص (رموز) وعداد يخصم منه تلقائيًا
  • إرفاق الأرصدة بخطط الاشتراك (مع الاستخدام الزائد وبدونه) وبمنتج شحن لمرة واحدة
  • ربط نقطة نهاية 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.

1

Navigate to Credits

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

Configure the credit unit

أدخل التفاصيل الأساسية لرصيد الرموز:اسم الرصيد: API Tokensنوع الرصيد: اختر Custom Unitاسم الوحدة: tokenالدقة: 0 (الرموز دائمًا أعداد صحيحة)انتهاء صلاحية الرصيد: 30 days (تُعاد تهيئة الأرصدة في كل دورة فوترة)
لا يمكن تغيير الدقة بعد إنشاء الرصيد. بالنسبة إلى أعداد الرموز، فإن 0 (الأعداد الصحيحة) هو الخيار الصحيح دائمًا تقريبًا.
3

Skip overage at the credit level

اترك الاستخدام الزائد معطلًا هنا — ستضبطه لكل خطة عند إرفاق الرصيد بالمنتجات. يتيح ذلك لخطة Starter حظر الاستخدام عند الصفر، بينما تسمح خطة Pro بالاستخدام الزائد.
إعدادات الاستخدام الزائد التي تضبطها هنا هي إعدادات افتراضية. يمكن لكل إرفاق بالمنتج تجاوزها — وهذا بالضبط ما سنفعله في الخطوة 3.
4

Save and copy the credit ID

انقر على Create Credit. بعد الحفظ، افتح الرصيد وانسخ معرّفه — ويبدو بالشكل cent_xxxxxxxxxxxx.
أصبح استحقاق رصيد API Tokens جاهزًا. بعد ذلك، أنشئ عدادًا حتى تتمكن أحداث الاستخدام من تشغيل الخصومات تلقائيًا.

الخطوة 2: إنشاء عداد لاستخدام الرموز

يجمع العداد أحداث الاستخدام الواردة ويحوّلها إلى خصومات من الأرصدة. تحتاج إليه قبل إنشاء منتجات الخطط، إذ ستُرفقه أثناء إنشاء المنتجات في الخطوة 3.
1

Open the Meters section

  1. في الشريط الجانبي للوحة التحكم، انتقل إلى ProductsMeters
  2. انقر على Create Meter
2

Configure the meter

أدخل ما يلي:اسم العداد: Token Usage Meterاسم الحدث: api.tokens_used (يجب أن يطابق تمامًا ما يرسله تطبيقك)نوع التجميع: Sum — نجمع عدد الرموز من كل حدثالخاصية: tokens — مفتاح البيانات الوصفية في كل حدث الذي ستُجمع قيمتهوحدة القياس: tokens
أسماء الأحداث حساسة لحالة الأحرف. api.tokens_usedApi.Tokens.Used — اختر اسمًا واحدًا والتزم به.
احفظ العداد وانسخ معرّفه — ستشير إليه عند إرفاقه بالمنتجات.
تم إنشاء العداد. يمكننا الآن ربطه بالرصيد عند ضبط المنتجات.

الخطوة 3: إنشاء منتجات الخطط

يجب أن يكون كلا المنتجين من نوع Usage Based Billing، وليس Subscription عاديًا — فلا يمكن إرفاق العدادات إلا بمنتجات UBB، وأنت تحتاج إلى العداد لخصم الأرصدة تلقائيًا أثناء استدعاء العملاء لواجهة API الخاصة بك. ما تزال منتجات UBB تدعم رسمًا أساسيًا متكررًا ($29 / $99)؛ وتُفوتر الاستخدامات الإضافية بالأرصدة.
إعداد تسعير Usage Based Billing

Usage Based Billing pricing type with meter configuration.

خطة Starter (‏29 دولارًا/شهريًا — 10M رمز، دون استخدام زائد)

1

Create the Starter UBB product

  1. انتقل إلى Products → Create Product
  2. اختر Usage Based Billing كنوع التسعير
  3. أدخل ما يلي:
اسم المنتج: NeuralAPI Starterالوصف: 10 million API tokens per month. Perfect for individual developers and small projects.السعر الثابت: 29.00 (الرسم الأساسي المتكرر — يُفوتر شهريًا حتى قبل وجود أي استخدام)دورة الفوترة: Monthlyالعملة: USD
2

Attach the meter

في قسم Select meter، انقر على + وأضف Token Usage Meter. ثم في العداد:
  1. فعّل Bill usage in Credits
  2. استحقاق الرصيد: اختر API Tokens
  3. وحدات العداد لكل رصيد: 1 — يطابق كل رمز في الحدث رصيدًا واحدًا مخصومًا
  4. الحد المجاني: 0 — يُعد تخصيص الرصيد نفسه “المستوى المجاني” للعميل؛ ولا نحتاج إلى نطاق مجاني إضافي
عداد مع تفعيل Bill usage in Credits واختيار API Tokens

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.

هذا هو الربط الذي يجعل أحداث api.tokens_used الواردة تخصم فعليًا من رصيد العميل.
3

Configure credit issuance for Starter

وأنت ما تزال داخل المنتج، مرّر إلى قسم إعداد الرصيد الذي يظهر بعد إرفاق عداد تتم فوترته بالأرصدة:الأرصدة المُصدرة لكل دورة فوترة: 10000000السماح بالاستخدام الزائد: معطل — يُحظر عملاء Starter عند نفاد الرموزاستيراد إعدادات الرصيد الافتراضية: مفعّل — استخدم انتهاء الصلاحية بعد 30 يومًا من استحقاق الرصيد
نموذج إعداد الرصيد مع مبلغ كل دورة وإعدادات الاستخدام الزائد

Configure credit issuance per cycle on the UBB product.

انقر على Save وانسخ معرّف المنتج.
خطة Starter: رسم أساسي قدره 29 دولارًا شهريًا، و10M رمز/دورة، ومحظورة عند الصفر، مع خصم تلقائي عبر العداد.

خطة Pro (‏99 دولارًا/شهريًا — 40M رمز، الاستخدام الزائد مفعّل)

1

Create the Pro UBB product

نفس خطوات Starter، مع أرقام أكبر:اسم المنتج: NeuralAPI Proالوصف: 40 million API tokens per month with overage. Built for production applications.السعر الثابت: 99.00دورة الفوترة: Monthlyالعملة: USD
2

Attach the meter

مطابق لـ Starter: أضف Token Usage Meter، وفعّل Bill usage in Credits، واختر API Tokens، واضبط وحدات العداد لكل رصيد على 1، والحد المجاني على 0.
3

Configure credit issuance with overage

اضبط إصدار الرصيد، مع تفعيل الاستخدام الزائد هذه المرة:الأرصدة المُصدرة لكل دورة فوترة: 40000000استيراد إعدادات الرصيد الافتراضية: معطل — نحتاج إلى تخصيص إعدادات الاستخدام الزائد لكل منتجالسماح بالاستخدام الزائد: مفعّلالسعر لكل وحدة: 0.000005 دولار لكل رمز (أي 0.005 دولار لكل 1K رمز، أو 5 دولارات لكل 1M رمز — أعلى من معدل الخطة الفعلي لكل رمز للحد من التجاوز)سلوك الاستخدام الزائد: Bill overage at billing — يُفرض رسم الاستخدام الزائد في الفاتورة التالية، ثم يُعاد ضبط الرصيداحفظ المنتج وانسخ معرّفه.
خطة Pro: رسم أساسي قدره 99 دولارًا شهريًا، و40M رمز/دورة، واستخدام زائد بسعر 0.005 دولار لكل 1K رمز، مع خصم تلقائي عبر العداد.

الخطوة 4: إنشاء حزمة شحن الرموز

حزمة الشحن هي عملية شراء لمرة واحدة تمنح 5,000,000 رمز إلى رصيد عميل موجود.
قسم تسعير المنتج مع اختيار Single Payment

Single Payment pricing selected for a one-time credit product.

1

Create a one-time product

  1. انتقل إلى Products → Create Product
  2. اختر Single Payment كنوع التسعير
  3. أدخل ما يلي:
اسم المنتج: Token Top-Up Packالوصف: Instantly add 5 million tokens to your NeuralAPI balance.السعر: 19.00العملة: USD
2

Attach the token credit

  1. في قسم Entitlements، انقر على Attach بجوار Credits
  2. اختر API Tokens
  3. اضبط الأرصدة المُصدرة على: 5000000
  4. عطّل Import Default Credit Settings — نريد تجاوز انتهاء الصلاحية الافتراضي بعد 30 يومًا
  5. اضبط انتهاء صلاحية الرصيد على: 365 days
  6. احفظ المنتج
انسخ معرّف المنتج.
لماذا مدة انتهاء صلاحية أطول لحزم الشحن؟ تُعاد تهيئة أرصدة الاشتراك كل 30 يومًا لأن هذه هي الدورة. أما حزم الشحن فهي مشتريات مدفوعة مسبقًا — دفع العميل 19 دولارًا مقدمًا، ومن المنطقي أن يتوقع بقاء الرموز لأكثر من شهر. تتوافق مدة 365 يومًا مع طريقة عمل الأرصدة المدفوعة مسبقًا الفعلية لدى OpenAI وAWS وAnthropic، مع إبقاء مسؤوليتك المالية محدودة حتى لا يتمكن العملاء من التخزين إلى أجل غير مسمى.
تم إعداد حزمة الشحن — ويمنح شراؤها 5,000,000 رمز تظل صالحة لمدة 365 يومًا.

الخطوة 5: إنشاء النظام الخلفي

لننشئ الآن خادم Express الذي يتعامل مع إتمام الاشتراك، وإتمام شراء الشحن، وعمليات completion الحقيقية من OpenAI مع فوترة الرموز، والاستعلامات عن الرصيد، وأحداث webhooks الخاصة بالأرصدة.
1

Set up your project

أنشئ tsconfig.json:
tsconfig.json
حدّث نصوص scripts في package.json:
package.json
2

Set up environment variables

أنشئ .env باستخدام بيانات الاعتماد والمعرّفات من الخطوات السابقة:
.env
لا ترفع .env أبدًا إلى نظام التحكم في الإصدارات. أضفه إلى .gitignore فورًا.
ستملأ DODO_PAYMENTS_WEBHOOK_KEY في الخطوة 7 بعد تسجيل نقطة نهاية webhook الخاصة بك.
3

Implement the server

أنشئ src/server.ts:
اكتمل النظام الخلفي: إتمام الاشتراك، وإتمام شراء الشحن، وcompletion من OpenAI مع فوترة الرموز عبر العداد، والاستعلام عن الرصيد، ومعالج webhook تم التحقق منه.
يوفر @dodopayments/ingestion-blueprints متتبعات جاهزة للاستخدام تعمل على أتمتة استدعاء usageEvents.ingest نيابةً عنك — بما في ذلك استخدام LLM Blueprint وAPI gateway وobject storage وstreams وtime-range.
4

A note on how deductions actually happen

ربما لاحظت عدم وجود استدعاء صريح من نوع “خصم N من الأرصدة”. وهذا مقصود:
  1. يستدعي معالجك OpenAI ويحصل على usage.total_tokens (مثلًا، 1532).
  2. تُدخل حدث استخدام واحدًا: event_name: api.tokens_used، metadata: { tokens: 1532 }.
  3. يجمع Token Usage Meter الأحداث حسب العميل.
  4. لأن العداد مرتبط برصيد API Tokens مع تفعيل Bill usage in Credits، تخصم Dodo Payments 1532 رصيدًا من أقدم منحة غير منتهية الصلاحية للعميل (FIFO).
  5. إذا كان الاستخدام الزائد مفعّلًا وانخفض العميل إلى ما دون الصفر، يُتتبّع العجز وتُفرض تكلفته في الفاتورة التالية.
يتولى العداد كل ذلك. لا يقوم رمزك إلا بإدخال الأحداث.

الخطوة 6: إضافة واجهة أمامية تجريبية

أنشئ public/index.html لاختبار جميع التدفقات في متصفحك. نحتفظ بمعرّف العميل في localStorage حتى تشترك → تنشئ → تشحن باستخدام الهوية نفسها، لمحاكاة تطبيق سجّل المستخدم الدخول إليه:

الخطوة 7: ربط webhook

تتيح webhooks لخادمك التفاعل مع تغييرات الرصيد — وستستخدمها لإرسال رسائل بريد إلكتروني تفيد بأن الرصيد “ينخفض” قبل وصول العملاء إلى الصفر.
1

Expose your local server

تحتاج webhooks إلى عنوان URL عامًا. للتطوير المحلي، استخدم ngrok أو أي نفق آخر:
انسخ عنوان URL الخاص بـ https://...ngrok-free.app.
2

Register the webhook in Dodo Payments

  1. في لوحة التحكم، انتقل إلى Developers → Webhooks → Add Endpoint
  2. URL: https://your-tunnel.ngrok-free.app/webhooks/dodo
  3. اشترك في الأحداث التالية (كحد أدنى):
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. احفظ وانسخ Signing Secret
  5. الصقه في .env بوصفه DODO_PAYMENTS_WEBHOOK_KEY، ثم أعد تشغيل npm run dev
يتحقق dodo.webhooks.unwrap() في SDK من رؤوس webhook-id وwebhook-timestamp وwebhook-signature باستخدام سر التوقيع الخاص بك. لا تحتاج إلى تنفيذ التحقق من HMAC يدويًا — ولا ينبغي لك ذلك، لأن Dodo Payments يستخدم Standard Webhooks، التي توقّع id.timestamp.body بدلًا من توقيع النص الأساسي وحده.

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

1

Subscribe a test customer

  1. شغّل npm run dev
  2. افتح http://localhost:3000
  3. اختر خطة Pro، وأدخل بريدًا إلكترونيًا واسمًا للاختبار، وانقر على Get Checkout Link، وأكمل الدفع باستخدام بيانات بطاقة الاختبار
  4. في لوحة التحكم، انتقل إلى Customers → most recent وانسخ معرّف cus_...
  5. الصقه في حقل “معرّف العميل الذي سجّل الدخول” في العرض التجريبي وانقر على Save
يجب أن يمتلك العميل 40,000,000 رمز. انقر على Refresh Balance للتأكيد.
2

Generate a real AI response

اكتب prompt وانقر على Generate. يستدعي الخادم OpenAI، ويحصل على total_tokens الفعلي، ويدخل حدث استخدام، ثم يعيد الاستجابة.
تُعالج أحداث الاستخدام بواسطة عامل في الخلفية كل نحو دقيقة. لن ينخفض الرصيد فورًا — انتظر من 30 إلى 90 ثانية وانقر على Refresh Balance مرة أخرى. لا تستنتج أن النظام معطل إذا لم يُظهر التحديث الأول أي تغيير.
3

Test the top-up flow

انقر على Buy 5M Tokens — $19 وأكمل عملية الدفع. بعد نجاح الدفع، حدّث الرصيد — يجب أن يزيد بمقدار 5,000,000 رمز. يجب أن يعرض سجل الخادم حدث credit.added.

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

الأسباب المحتملة:
  • لا يطابق اسم حدث العداد event_name الذي ترسله (api.tokens_used حساس لحالة الأحرف)
  • العداد غير مرتبط برصيد API Tokens في المنتج — انتقل إلى إعدادات عداد المنتج وتأكد من تفعيل Bill usage in Credits
  • لا يطابق مفتاح metadata.tokens حقل “Over Property” في العداد
  • انتهت صلاحية منحة العميل (تحقق من سجل أرصدة العميل)
ما يجب التحقق منه:
  1. Products → Meters: افتح العداد وتأكد من ظهور اسم الرصيد المرتبط في إرفاق المنتج
  2. علامة تبويب Events في العداد — يجب أن تظهر الأحداث المُدخلة هناك حتى قبل الخصم
  3. Customers → [Customer] → Credits: يجب أن تظهر إدخالات السجل خلال دقيقة أو دقيقتين
الأسباب المحتملة:
  • لم يُكمل العميل عملية الدفع بعد — لا تُصدر الأرصدة إلا بعد نجاح الدفع
  • تستعلم باستخدام customer_id غير صحيح (استخدم معرّف cus_... من لوحة التحكم، وليس معرّف قاعدة بياناتك)
  • لا يطابق CREDIT_ENTITLEMENT_ID في .env الرصيد المرفق بالمنتج
ما يجب التحقق منه: افتح Customers → [Customer] → Credits. إذا لم تظهر أي أرصدة هناك، فلم يُرفق استحقاق المنتج أو لم تكتمل عملية الدفع.
الأسباب المحتملة:
  • لم يُفعّل الاستخدام الزائد في إرفاق رصيد منتج Pro (إعداد مستوى الرصيد ليس سوى إعداد افتراضي)
  • العميل مشترك فعليًا في Starter وليس Pro
  • تم ضبط حد الاستخدام الزائد على 0
ما يجب التحقق منه: عدّل Pro → Entitlements → Credits → وتأكد من تفعيل Allow Overage وأن Price Per Unit هو 0.000005 (= 5 دولارات لكل مليون رمز؛ تحقق مرة أخرى من الأصفار البادئة — فالحقل يقبل سعر كل رمز، وليس سعر كل 1K).
الأسباب المحتملة:
  • ترتيب تحليل النص: تم تطبيق 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

Starter (10M، حد صارم) وPro (40M + استخدام زائد) مضبوطتان لكل منتج دون تكرار الرصيد

One-Time Top-Up Pack

يمكن للعملاء إضافة 5M رمز مقابل 19 دولارًا دون تغيير اشتراكهم

Auto-Deduction via Meter

تُدخل أعداد رموز OpenAI الحقيقية كأحداث؛ ويخصم العداد الأرصدة وفق FIFO دون تتبع يدوي

Live Balance API

رصيد مباشر عبر SDK للتحكم في الوصول أو عرض الاستخدام أو تحذير العملاء داخل التطبيق

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 يتحقق من الرصيد فقط، وليس من حالة الاشتراك. لذلك قد يواصل العميل الملغى استهلاك رموزه المتبقية. هذا هو الإعداد الافتراضي الملائم للمستهلك. إذا أردت تحكمًا أكثر صرامة في الوصول، فإما (أ) استمع إلى webhook subscription.cancelled وتحكم في /api/generate بناءً على حالة الاشتراك، أو (ب) استدعِ API السجل الخاص بـ Dodo لخصم أرصدة الخطة غير المستخدمة عند الإلغاء مع إبقاء أرصدة الشحن كما هي.
  • راقب لوحة Usage Billing لاكتشاف الحالات الشاذة في القياس مبكرًا.

Credit-Based Billing Reference

وثائق CBB الكاملة: الترحيل، وأنماط الاستخدام الزائد، وإدارة السجل، وجميع نقاط نهاية API.

Credit Webhook Events

مخططات payload لكل حدث رصيد قد يتلقاه خادمك.
آخر تعديل في ٣١ يوليو ٢٠٢٦