> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust

> دمج Dodo Payments في تطبيقات Rust الخاصة بك باستخدام SDK قوي مكتوب بنمط غير متزامن يعتمد على Tokio وreqwest

يوفر Rust SDK وصولاً مناسبًا ومبنيًا على النمط غير المتزامن إلى Dodo Payments REST API من التطبيقات المكتوبة بلغة Rust. يقدم الطلبات والاستجابات المكتوبة بقوة، والمساعدين المدمجين للتصفح، والمهلات القابلة للتكوين والبيئات.

## التثبيت

أضف SDK إلى مشروعك باستخدام Cargo:

```bash theme={null}
cargo add dodopayments
```

أو أضفها يدويًا إلى `Cargo.toml`:

```toml theme={null}
[dependencies]
dodopayments = "1.106.0"
tokio = { version = "1", features = ["full"] }
serde_json = "1"
futures = "0.3" # required for streaming paginated results
```

<Info>
  يتطلب SDK إصدار Rust 1.75 أو أحدث، مستفيدًا من ميزات النمط غير المتزامن الحديثة لأداء مثالي.
</Info>

## البداية السريعة

يقوم العميل بقراءة مفتاح API الخاص بك من متغير البيئة `DODO_PAYMENTS_API_KEY` افتراضيًا. قم بتهيئة العميل وقم بإنشاء جلسة الدفع الأولى الخاصة بك:

```rust theme={null}
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(())
}
```

<Warning>
  احفظ دائمًا مفاتيح API الخاصة بك بشكل آمن باستخدام متغيرات البيئة. لا تقم بتثبيتها بشكل مباشر في شفرة المصدر الخاصة بك.
</Warning>

## الميزات الأساسية

<CardGroup cols={2}>
  <Card title="Async First" icon="bolt">
    مبني باستخدام Tokio وreqwest بدعم `async`/`await` في جميع الأنحاء
  </Card>

  <Card title="Strong Typing" icon="shield-check">
    الطلبات والاستجابات المكتوبة بقوة لأمان وقت الترجمة
  </Card>

  <Card title="Auto-Pagination" icon="layer-group">
    بث كل عنصر عبر الصفحات أو تقدم صفحة واحدة في كل مرة
  </Card>

  <Card title="Configurable" icon="sliders">
    تكوين البيئات والمهلات وعناوين URL الأساسية لكل عميل
  </Card>
</CardGroup>

## التكوين

### متغيرات البيئة

افتراضيًا، يقرأ `Client::from_env()` مفتاح API الخاص بك من متغير البيئة `DODO_PAYMENTS_API_KEY` ويستخدم عنوان URL الأساسي الافتراضي ما لم تقم بتعيين `DODO_PAYMENTS_BASE_URL`:

```bash theme={null}
export DODO_PAYMENTS_API_KEY="your_api_key"
export DODO_PAYMENTS_BASE_URL="https://test.dodopayments.com" # optional
```

يمكنك أيضًا تهيئة العميل بشكل صريح. يعيد `Client::new` قيمة `Result`، لذا قم بفكها باستخدام `?` داخل دالة تعيد `dodopayments::Result`:

```rust theme={null}
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_mode` | `https://live.dodopayments.com` |
| `test_mode` | `https://test.dodopayments.com` |

عنوان URL الأساسي الافتراضي هو `https://live.dodopayments.com`. اختر بيئة أخرى باستخدام `Environment` enum بدلاً من ترميز عناوين URL يدويًا:

```rust theme={null}
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()` أثناء استهداف بيئة غير افتراضية، تجاوزها على التكوين:

```rust theme={null}
use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(ClientConfig::from_env()?.with_environment(Environment::TestMode))?;
```

### المهلات

مهلة الطلب الافتراضية هي 30 ثانية. تجاوزها لكل عميل:

```rust theme={null}
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)),
)?;
```

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

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

قم بإنشاء جلسة دفع:

```rust theme={null}
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:?}");
```

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

قم بإنشاء واسترجاع معلومات العميل:

```rust theme={null}
// 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:?}");
```

### معالجة الاشتراكات

إنشاء وإدارة الاشتراكات المتكررة:

```rust theme={null}
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:?}");
```

<Info>
  يتطلب `billing` على الأقل الرمز `country` المكون من حرفين ISO. يعتبر `customer` نوع `CustomerRequest` enum — مرر `AttachExisting` لعميل موجود أو `New` لعميل جديد. يتم تقديم الحقول المتعلقة بالمبالغ مثل `product_price` في أدنى فئة عملة (مثلًا، `2500` = \$25.00 USD).
</Info>

## الفوترة المستندة إلى الاستخدام

### تجميع أحداث الاستخدام

تتبع الأحداث المخصصة:

```rust theme={null}
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:?}");
```

### قائمة أحداث الاستخدام

```rust theme={null}
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`:

```rust theme={null}
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`:

```rust theme={null}
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 بشكل مختلف عن أخطاء النقل:

```rust theme={null}
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 الأساسي:

```rust theme={null}
let response = client
    .request(reqwest::Method::GET, "/some/path")
    .send()
    .await?;
```

## الموارد

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-rust">
    عرض الشفرة المصدرية والمساهمة
  </Card>

  <Card title="Crates.io" icon="cube" href="https://crates.io/crates/dodopayments">
    عرض الحزمة والمنشورات
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    وثائق API الكاملة
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    احصل على المساعدة واتصل بالمطورين
  </Card>
</CardGroup>

## الدعم

هل تحتاج إلى مساعدة مع Rust SDK؟

* **Discord**: انضم إلى [الخادم المجتمعي](https://discord.gg/bYqAp4ayYh) للحصول على دعم في الوقت الحقيقي
* **Email**: تواصل معنا عبر [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: افتح مشكلة على [المستودع](https://github.com/dodopayments/dodopayments-rust/issues)

## المساهمة

نرحب بالمساهمات! تحقق من [إرشادات المساهمة](https://github.com/dodopayments/dodopayments-rust/blob/main/CONTRIBUTING.md) للبدء.