يوفر Rust SDK وصولاً مناسبًا ومبنيًا على النمط غير المتزامن إلى Dodo Payments REST API من التطبيقات المكتوبة بلغة Rust. يقدم الطلبات والاستجابات المكتوبة بقوة، والمساعدين المدمجين للتصفح، والمهلات القابلة للتكوين والبيئات.
التثبيت
أضف SDK إلى مشروعك باستخدام Cargo:
أو أضفها يدويًا إلى Cargo.toml:
[ dependencies ]
dodopayments = "1.106.0"
tokio = { version = "1" , features = [ "full" ] }
serde_json = "1"
futures = "0.3" # required for streaming paginated results
يتطلب SDK إصدار Rust 1.75 أو أحدث، مستفيدًا من ميزات النمط غير المتزامن الحديثة لأداء مثالي.
البداية السريعة
يقوم العميل بقراءة مفتاح API الخاص بك من متغير البيئة DODO_PAYMENTS_API_KEY افتراضيًا. قم بتهيئة العميل وقم بإنشاء جلسة الدفع الأولى الخاصة بك:
use dodopayments :: Client ;
#[tokio :: main]
async fn main () -> dodopayments :: Result <()> {
let client = Client :: from_env () ? ;
let result = client
. checkout_sessions ()
. create ()
. body ( dodopayments :: models :: CheckoutSessionsCreateParams {
product_cart : Some ( vec! [ dodopayments :: models :: ProductItemReq {
product_id : "product_id" . to_string (),
quantity : 1 ,
addons : None ,
amount : None ,
credit_entitlements : None ,
}]),
.. Default :: default ()
})
. await ? ;
println! ( "{result:?}" );
Ok (())
}
احفظ دائمًا مفاتيح 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:
export DODO_PAYMENTS_API_KEY = "your_api_key"
export DODO_PAYMENTS_BASE_URL = "https://test.dodopayments.com" # optional
يمكنك أيضًا تهيئة العميل بشكل صريح. يعيد Client::new قيمة Result، لذا قم بفكها باستخدام ? داخل دالة تعيد dodopayments::Result:
use dodopayments :: { Client , ClientConfig };
#[tokio :: main]
async fn main () -> dodopayments :: Result <()> {
let client = Client :: new (
ClientConfig :: new ( "https://live.dodopayments.com" ) . with_api_key ( "My API Key" ),
) ? ;
println! ( "{}" , client . base_url ());
Ok (())
}
البيئات
الاسم عنوان URL الأساسي live_modehttps://live.dodopayments.comtest_modehttps://test.dodopayments.com
عنوان URL الأساسي الافتراضي هو https://live.dodopayments.com. اختر بيئة أخرى باستخدام Environment enum بدلاً من ترميز عناوين URL يدويًا:
use dodopayments :: { Client , ClientConfig , Environment };
let client = Client :: new (
ClientConfig :: from_environment ( Environment :: TestMode ) . with_api_key ( "My API Key" ),
) ? ;
للاستمرار في قراءة مفتاح API من DODO_PAYMENTS_API_KEY عبر from_env() أثناء استهداف بيئة غير افتراضية، تجاوزها على التكوين:
use dodopayments :: { Client , ClientConfig , Environment };
let client = Client :: new ( ClientConfig :: from_env () ?. with_environment ( Environment :: TestMode )) ? ;
المهلات
مهلة الطلب الافتراضية هي 30 ثانية. تجاوزها لكل عميل:
use std :: time :: Duration ;
use dodopayments :: { Client , ClientConfig };
let client = Client :: new (
ClientConfig :: new ( "https://live.dodopayments.com" )
. with_api_key ( "My API Key" )
. with_timeout ( Duration :: from_secs ( 60 )),
) ? ;
العمليات الشائعة
إنشاء جلسة الدفع
قم بإنشاء جلسة دفع:
let session = client
. checkout_sessions ()
. create ()
. body ( dodopayments :: models :: CheckoutSessionsCreateParams {
product_cart : Some ( vec! [ dodopayments :: models :: ProductItemReq {
product_id : "prod_123" . to_string (),
quantity : 1 ,
addons : None ,
amount : None ,
credit_entitlements : None ,
}]),
return_url : Some ( "https://yourdomain.com/return" . to_string ()),
.. Default :: default ()
})
. await ? ;
println! ( "{session:?}" );
إدارة العملاء
قم بإنشاء واسترجاع معلومات العميل:
// Create a customer
let customer = client
. customers ()
. create ()
. body ( dodopayments :: models :: CustomerCreateParams {
email : "customer@example.com" . to_string (),
name : "John Doe" . to_string (),
.. Default :: default ()
})
. await ? ;
// Retrieve a customer
let customer = client
. customers ()
. retrieve ( "cus_123" )
. await ? ;
println! ( "{customer:?}" );
معالجة الاشتراكات
إنشاء وإدارة الاشتراكات المتكررة:
let subscription = client
. subscriptions ()
. create ()
. body ( dodopayments :: models :: SubscriptionCreateParams {
billing : dodopayments :: models :: BillingAddress {
country : "US" . to_string (),
city : "San Francisco" . to_string (),
state : "CA" . to_string (),
street : "1 Market St" . to_string (),
zipcode : "94105" . to_string (),
},
customer : dodopayments :: models :: CustomerRequest :: AttachExisting (
dodopayments :: models :: AttachExistingCustomer {
customer_id : "cus_123" . to_string (),
},
),
product_id : "pdt_456" . to_string (),
quantity : 1 ,
.. Default :: default ()
})
. await ? ;
println! ( "{subscription:?}" );
يتطلب billing على الأقل الرمز country المكون من حرفين ISO. يعتبر customer نوع CustomerRequest enum — مرر AttachExisting لعميل موجود أو New لعميل جديد. يتم تقديم الحقول المتعلقة بالمبالغ مثل product_price في أدنى فئة عملة (مثلًا، 2500 = $25.00 USD).
الفوترة المستندة إلى الاستخدام
تجميع أحداث الاستخدام
تتبع الأحداث المخصصة:
let response = client
. usage_events ()
. ingest ()
. body ( dodopayments :: models :: UsageEventsIngestParams {
events : vec! [ dodopayments :: models :: EventInput {
event_id : "api_call_12345" . to_string (),
customer_id : "cus_abc123" . to_string (),
event_name : "api_request" . to_string (),
.. Default :: default ()
}],
})
. await ? ;
println! ( "{response:?}" );
قائمة أحداث الاستخدام
let events = client
. usage_events ()
. list ()
. query ( serde_json :: json! ({
"customer_id" : "cus_abc123" ,
"event_name" : "api_request" ,
}))
. await ? ;
for event in & events . items {
println! ( "{event:?}" );
}
التصفح
تقوم نقاط النهاية للقائمة بإعادة صفحة مكتوبة يحتوي حقل items على الصفحة الحالية من النتائج. بث كل عنصر عبر جميع الصفحات باستخدام into_stream:
use futures :: StreamExt ;
let mut items = Box :: pin (
client
. payments ()
. list ()
. query ( serde_json :: json! ({}))
. await ?
. into_stream (),
);
while let Some ( item ) = items . next () . await {
let item = item ? ;
println! ( "{item:?}" );
}
أو تقدم صفحة واحدة في كل مرة باستخدام get_next_page:
let mut page = client
. payments ()
. list ()
. query ( serde_json :: json! ({}))
. await ? ;
loop {
for item in & page . items {
println! ( "{item:?}" );
}
match page . get_next_page () . await ? {
Some ( next ) => page = next ,
None => break ,
}
}
معالجة الأخطاء
كل طريقة تعيد dodopayments::Result<T>. يتم تمثيل الفشل بواسطة نوع dodopayments::Error enum. قم بمطابقته للتعامل مع أخطاء API بشكل مختلف عن أخطاء النقل:
let result = client
. checkout_sessions ()
. create ()
. body ( dodopayments :: models :: CheckoutSessionsCreateParams {
product_cart : Some ( vec! [ dodopayments :: models :: ProductItemReq {
product_id : "product_id" . to_string (),
quantity : 1 ,
addons : None ,
amount : None ,
credit_entitlements : None ,
}]),
.. Default :: default ()
})
. await ;
match result {
Ok ( value ) => println! ( "{value:?}" ),
Err ( dodopayments :: Error :: Api { status , message }) => {
eprintln! ( "API returned {status}: {message}" );
}
Err ( err ) => eprintln! ( "request failed: {err}" ),
}
نقاط النهاية غير الموثقة
لإجراء اتصال بنقطة نهاية لم يتم الكشف عنها بعد كطريقة مكتوبة، استخدم أداة request منخفضة المستوى، التي تطبق المصادقة وعنوان URL الأساسي:
let response = client
. request ( reqwest :: Method :: GET , "/some/path" )
. send ()
. await ? ;
الموارد
GitHub Repository عرض الشفرة المصدرية والمساهمة
Crates.io عرض الحزمة والمنشورات
API Reference وثائق API الكاملة
Discord Community احصل على المساعدة واتصل بالمطورين
الدعم
هل تحتاج إلى مساعدة مع Rust SDK؟
المساهمة
نرحب بالمساهمات! تحقق من إرشادات المساهمة للبدء.