Skip to main content
يوفّر Rust SDK لتطبيقات Rust غير المتزامنة وصولًا مكتوب الأنواع إلى REST API الخاص بـ Dodo Payments. وقد بُني باستخدام Tokio و reqwest، ويستخدم هياكل طلبات واستجابات مكتوبة الأنواع، ويبث النتائج المُقسّمة إلى صفحات، ويعيد محاولة الطلبات الفاشلة.

التثبيت

أضف 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 الخاص بوضع الاختبار في وضع الاختبار فقط.
احتفظ بمفاتيح 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:
لا يقرأ Rust SDK المتغير DODO_PAYMENTS_WEBHOOK_KEY، ولا يحتوي على طريقة للتحقق من توقيعات webhook. للتحقق منها، اتبع Webhooks. يمكنك أيضًا إعداد العميل بشكل صريح. يعيد Client::new قيمة Result، لذا استخدم unwrap معها عبر ? داخل دالة تُرجع dodopayments::Result:

البيئات

يحتوي SDK على بيئتين: عنوان URL الأساسي الافتراضي هو https://live.dodopayments.com. لاختيار بيئة أخرى، استخدم تعداد Environment بدلًا من عنوان URL مُضمّن بشكل ثابت:
للاستمرار في قراءة مفتاح API من DODO_PAYMENTS_API_KEY باستخدام from_env() مع استهداف بيئة أخرى، تجاوز البيئة في الإعدادات:

المهل الزمنية

المهلة الزمنية الافتراضية للطلب هي 30 ثانية. تجاوزها لعميل باستخدام with_timeout:
يعيد العميل محاولة أخطاء الاتصال والاستجابات ذات رموز الحالة 408 أو 409 أو 429 أو 500 وما فوق. ويعيد المحاولة مرتين افتراضيًا، مع تأخير أُسّي، وينتظر ترويسة Retry-After عندما ترسلها API. لتغيير عدد مرات إعادة المحاولة، استدعِ with_max_retries على ClientConfig، مثل .with_max_retries(0) لتعطيل إعادة المحاولات.

العمليات الشائعة

تستخدم الأمثلة في هذا القسم client من البدء السريع.

إنشاء جلسة دفع

أنشئ جلسة دفع باستخدام عنوان URL للعودة:
أعِد توجيه العميل إلى session.checkout_url. يعمل كل عنوان URL للدفع مرة واحدة، وتنتهي صلاحيته بعد 24 ساعة. للاطلاع على كل خيار من خيارات الجلسة، راجع جلسات الدفع.

إدارة العملاء

أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرجعه باستخدام المعرّف:

التعامل مع الاشتراكات

أنشئ اشتراكًا لعميل موجود.
POST /subscriptions (طريقة subscriptions().create() في SDK) مهملة. ولا تزال تعمل مع عمليات الدمج الحالية، لكن ينبغي لعمليات الدمج الجديدة إنشاء الاشتراكات من خلال جلسة دفع.
يتطلب 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:

المساهمة

للمساهمة، اقرأ إرشادات المساهمة.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦