التثبيت
أضف SDK إلى مشروعك باستخدام Cargo:Cargo.toml:
يتطلب SDK الإصدار 1.75 من Rust أو إصدارًا أحدث.
البداية السريعة
Client::from_env() يقرأ مفتاح API الخاص بك من متغير البيئة DODO_PAYMENTS_API_KEY. أنشئ عميلًا، ثم أنشئ جلسة دفع:
DODO_PAYMENTS_API_KEY مضبوطًا، يعيد Client::from_env() قيمة Error::Config. يتصل العميل بالوضع المباشر ما لم تختر بيئة أخرى، كما هو موضح في البيئات. يعمل مفتاح API الخاص بوضع الاختبار في وضع الاختبار فقط.
الميزات الأساسية
Async First
مبني على Tokio و reqwest، مع
async/await لكل طلب.Strong Typing
هياكل طلبات واستجابات مكتوبة الأنواع لإجراء عمليات التحقق أثناء التجميع.
Auto-Pagination
بثّ كل عنصر عبر الصفحات، أو انتقل صفحة واحدة في كل مرة.
Configurable
عيّن البيئة وعنوان URL الأساسي والمهلة وعدد مرات إعادة المحاولة لكل عميل.
الإعدادات
متغيرات البيئة
Client::from_env() يقرأ مفتاح API الخاص بك من DODO_PAYMENTS_API_KEY. ويستخدم عنوان URL الخاص بالوضع المباشر ما لم تضبط DODO_PAYMENTS_BASE_URL:
DODO_PAYMENTS_WEBHOOK_KEY، ولا يحتوي على طريقة للتحقق من توقيعات webhook. للتحقق منها، اتبع Webhooks.
يمكنك أيضًا إعداد العميل بشكل صريح. يعيد Client::new قيمة Result، لذا استخدم unwrap معها عبر ? داخل دالة تُرجع dodopayments::Result:
البيئات
يحتوي SDK على بيئتين:
عنوان URL الأساسي الافتراضي هو
https://live.dodopayments.com. لاختيار بيئة أخرى، استخدم تعداد Environment بدلًا من عنوان URL مُضمّن بشكل ثابت:
DODO_PAYMENTS_API_KEY باستخدام from_env() مع استهداف بيئة أخرى، تجاوز البيئة في الإعدادات:
المهل الزمنية
المهلة الزمنية الافتراضية للطلب هي 30 ثانية. تجاوزها لعميل باستخدامwith_timeout:
Retry-After عندما ترسلها API. لتغيير عدد مرات إعادة المحاولة، استدعِ with_max_retries على ClientConfig، مثل .with_max_retries(0) لتعطيل إعادة المحاولات.
العمليات الشائعة
تستخدم الأمثلة في هذا القسمclient من البدء السريع.
إنشاء جلسة دفع
أنشئ جلسة دفع باستخدام عنوان URL للعودة:session.checkout_url. يعمل كل عنوان URL للدفع مرة واحدة، وتنتهي صلاحيته بعد 24 ساعة. للاطلاع على كل خيار من خيارات الجلسة، راجع جلسات الدفع.
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرجعه باستخدام المعرّف:التعامل مع الاشتراكات
أنشئ اشتراكًا لعميل موجود.يتطلب
billing فقط country، وهو أحد متغيرات تعداد CountryCode مثل CountryCode::Us. customer هو تعداد CustomerRequest: مرّر AttachExistingCustomer لعميل موجود أو NewCustomer لإنشاء عميل. لفرض رسوم على اشتراك عند الطلب، استدعِ client.subscriptions().charge().subscription_id(...) باستخدام نص SubscriptionsChargeParams. تكون حقول المبالغ مثل product_price بوحدة العملة الأصغر (على سبيل المثال، 2500 هو $25.00).الفوترة القائمة على الاستخدام
إدخال أحداث الاستخدام
أرسل أحداث الاستخدام لعميل:event_id هو مفتاح عدم التكرار، لذا امنح كل حدث قيمة فريدة. إذا كان timestamp هو None، فسيستخدم الحدث الوقت الحالي.
سرد أحداث الاستخدام
اسرد الأحداث التي تمت تصفيتها حسب العميل واسم الحدث. توضع عوامل التصفية في كائن استعلام JSON:تقسيم الصفحات
تعيد نقاط نهاية السرد صفحة مكتوبة الأنواع، ويحتوي حقلitems فيها على النتائج الحالية للصفحة. لبث كل عنصر عبر جميع الصفحات، استدعِ into_stream:
get_next_page. ويعيد None بعد الصفحة الأخيرة:
معالجة الأخطاء
تعيد كل طريقة قيمةdodopayments::Result<T>. وتكون حالات الفشل متغيرات من تعداد dodopayments::Error: Api لخطأ حالة صادر عن API، وHttp لأخطاء النقل، وJson لأخطاء التسلسل، وConfig لأخطاء الإعداد، وMissingPathParam أو MissingBody للطلبات غير المكتملة. طابق عليها لمعالجة أخطاء API بشكل منفصل عن أخطاء النقل:
نقاط النهاية غير الموثقة
لاستدعاء نقطة نهاية لا تحتوي على طريقة مكتوبة الأنواع، استخدم منشئrequest منخفض المستوى. فهو يطبّق المصادقة وعنوان URL الأساسي. لتسمية reqwest::Method، أضف reqwest 0.12 إلى تبعياتك:
الموارد
GitHub Repository
الشفرة المصدرية والإصدارات والقائمة الكاملة للطرق.
Crates.io
الحزمة المنشورة وإصداراتها.
API Reference
كل نقطة نهاية ومعامل واستجابة.
Discord Community
اطرح الأسئلة وتحدث مع المطورين الآخرين.
الدعم
للحصول على مساعدة بشأن Rust SDK:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل مع support@dodopayments.com.
- GitHub: افتح مشكلة في المستودع.