> ## 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.

# روبي

> دمج مدفوعات دودي في تطبيقات روبي الخاصة بك باستخدام SDK أنيق ومناسب للغة روبي

يوفر SDK روبي طريقة بسيطة وبديهية لدمج مدفوعات دودي في تطبيقات روبي الخاصة بك. يتبع تقاليد روبي وأفضل الممارسات، ويقدم معالجة شاملة للأخطاء، والترقيم، ودعم البرمجيات الوسيطة.

## التثبيت

أضف الجوهرة إلى ملف Gemfile الخاص بك:

```ruby Gemfile theme={null}
gem "dodopayments", "~> 2.9"
```

<Tip>
  استخدم دائمًا أحدث إصدار من SDK للوصول إلى أحدث ميزات Dodo Payments. شغّل `bundle update dodopayments` بانتظام للبقاء على اطلاع.
</Tip>

ثم قم بتشغيل:

```bash theme={null}
bundle install
```

<Info>
  يدعم الـ SDK روبي 3.2.0 والإصدارات الأحدث، مع أنواع شاملة، ومعالجة أخطاء، وآليات إعادة المحاولة.
</Info>

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

قم بتهيئة العميل وإنشاء جلسة دفع:

```ruby theme={null}
require "bundler/setup"
require "dodopayments"

dodo_payments = Dodopayments::Client.new(
  bearer_token: ENV["DODO_PAYMENTS_API_KEY"], # This is the default and can be omitted
  environment: "test_mode" # defaults to "live_mode"
)

checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

puts(checkout_session_response.session_id)
```

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

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

<CardGroup cols={2}>
  <Card title="Ruby Conventions" icon="gem">
    يتبع اصطلاحات التسمية في روبي والأنماط الاصطلاحية
  </Card>

  <Card title="Elegant Syntax" icon="code">
    واجهة برمجة تطبيقات نظيفة وقابلة للقراءة تبدو طبيعية لمطوّري روبي
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    مُكرِّرات التصفح التلقائي المدمجة لردود القوائم
  </Card>

  <Card title="Type Safety" icon="shield-check">
    أنواع Sorbet الاختيارية لتعزيز أمان النوع
  </Card>
</CardGroup>

## التكوين

### تكوين المهلة

قم بتكوين مهلات الطلبات:

```ruby theme={null}
# Configure default for all requests (default is 60 seconds)
dodo_payments = Dodopayments::Client.new(
  timeout: nil # disable timeout
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {timeout: 5}
)
```

### تكوين إعادة المحاولة

قم بتكوين سلوك إعادة المحاولة التلقائي:

```ruby theme={null}
# Configure default for all requests (default is 2)
dodo_payments = Dodopayments::Client.new(
  max_retries: 0 # disable retries
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {max_retries: 5}
)
```

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

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

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

```ruby theme={null}
session = dodo_payments.checkout_sessions.create(
  product_cart: [
    {
      product_id: "prod_123",
      quantity: 1
    }
  ],
  return_url: "https://yourdomain.com/return"
)

# Redirect to checkout
redirect_to session.checkout_url
```

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

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

```ruby theme={null}
# Create a customer
customer = dodo_payments.customers.create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: {
    user_id: "12345"
  }
)

# Retrieve customer
customer = dodo_payments.customers.retrieve("cus_123")
puts "Customer: #{customer.name} (#{customer.email})"
```

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

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

```ruby theme={null}
# Create a subscription
subscription = dodo_payments.subscriptions.create(
  billing: {
    country: "US",
    city: "San Francisco",
    state: "CA",
    street: "1 Market St",
    zipcode: "94105"
  },
  customer: { customer_id: "cus_123" }, # or { email: "...", name: "..." } for a new customer
  product_id: "pdt_456",
  quantity: 1
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge = dodo_payments.subscriptions.charge(
  subscription.subscription_id,
  product_price: 2500
)

# Update subscription metadata
updated = dodo_payments.subscriptions.update(
  subscription.subscription_id,
  metadata: { plan_type: "premium" }
)
```

<Info>
  `billing` يتطلب على الأقل رمز ISO ذو الحرفين `country` . `customer` يقبل إما `{ customer_id: "..." }` لإرفاق عميل موجود أو `{ email: "...", name: "..." }` لإنشاء عميل جديد. `product_price` في أدنى فئة عملة.
</Info>

## الصفحات

### التصفح التلقائي

التنقل تلقائيًا عبر جميع الصفحات:

```ruby theme={null}
page = dodo_payments.payments.list

# Fetch single item from page
payment = page.items[0]
puts(payment.brand_id)

# Automatically fetches more pages as needed
page.auto_paging_each do |payment|
  puts(payment.brand_id)
end
```

### التصفح اليدوي

للحصول على مزيد من التحكم في التصفح:

```ruby theme={null}
page = dodo_payments.payments.list

if page.next_page?
  new_page = page.next_page
  puts(new_page.items[0].brand_id)
end
```

## معالجة الأخطاء

تعامل مع أخطاء Dodo Payments API المختلفة:

```ruby theme={null}
begin
  checkout_session = dodo_payments.checkout_sessions.create(
product_cart: [{product_id: "product_id", quantity: 1}]
  )
rescue Dodopayments::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
rescue Dodopayments::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Dodopayments::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end
```

<Tip>
  قم بتنفيذ منطق المحاولة مرة أخرى مع تأخير متزايد لمعالجة أخطاء حد المعدل لضمان تعامل تطبيقك بسلاسة مع السيناريوهات ذات الحجم الكبير.
</Tip>

## أمان الأنواع مع Sorbet

استخدم Sorbet للحصول على معلمات طلب آمنة الأنواع:

```ruby theme={null}
# Type-safe using Sorbet RBI definitions
dodo_payments.checkout_sessions.create(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)

# Hashes work, but are not typesafe
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

# You can also splat a full Params class
params = Dodopayments::CheckoutSessionCreateParams.new(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)
dodo_payments.checkout_sessions.create(**params)
```

## الاستخدام المتقدم

### نقاط النهاية غير الموثقة

إجراء طلبات إلى نقاط نهاية غير موثقة:

```ruby theme={null}
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)
```

### معلمات غير موثقة

إرسال معلمات غير موثقة:

```ruby theme={null}
checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {
    extra_query: {my_query_parameter: value},
    extra_body: {my_body_parameter: value},
    extra_headers: {"my-header": value}
  }
)

# Access undocumented response properties
puts(checkout_session_response[:my_undocumented_property])
```

## تكامل Rails

### إنشاء مبدئي

إنشاء `config/initializers/dodo_payments.rb`:

```ruby theme={null}
require "dodopayments"

DODO_CLIENT = Dodopayments::Client.new(
  bearer_token: Rails.application.credentials.dodo_api_key,
  environment: Rails.env.production? ? "live_mode" : "test_mode"
)
```

### نمط كائن الخدمة

إنشاء خدمة دفع:

```ruby theme={null}
# app/services/payment_service.rb
class PaymentService
  def initialize
    @client = DODO_CLIENT
  end

  def create_checkout(items)
    @client.checkout_sessions.create(
      product_cart: items,
      return_url: Rails.application.routes.url_helpers.checkout_return_url
    )
  end

  def process_payment(amount:, currency:, customer_id:)
    @client.payments.create(
      amount: amount,
      currency: currency,
      customer_id: customer_id
    )
  end
end
```

### تكامل وحدة التحكم

استخدم في وحدات تحكم Rails الخاصة بك:

```ruby theme={null}
# app/controllers/checkouts_controller.rb
class CheckoutsController < ApplicationController
  def create
    service = PaymentService.new
    session = service.create_checkout(checkout_params[:items])
    
    redirect_to session.checkout_url, allow_other_host: true
  rescue Dodopayments::Errors::APIError => e
    flash[:error] = "Payment error: #{e.message}"
    redirect_to cart_path
  end

  private

  def checkout_params
    params.require(:checkout).permit(items: [:product_id, :quantity])
  end
end
```

## تكامل Sinatra

استخدام مع تطبيقات Sinatra:

```ruby theme={null}
require "sinatra"
require "dodopayments"

configure do
  set :dodo_client, Dodopayments::Client.new(
    bearer_token: ENV["DODO_API_KEY"]
  )
end

post "/create-checkout" do
  content_type :json
  
  begin
    session = settings.dodo_client.checkout_sessions.create(
      product_cart: JSON.parse(request.body.read)["items"],
      return_url: "#{request.base_url}/return"
    )
    
    { checkout_url: session.checkout_url }.to_json
  rescue Dodopayments::Errors::APIError => e
    status 400
    { error: e.message }.to_json
  end
end
```

## الموارد

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-ruby">
    عرض كود المصدر والمساهمة
  </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>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-ruby/issues">
    الإبلاغ عن أخطاء أو طلب ميزات
  </Card>
</CardGroup>

## الدعم

تحتاج إلى مساعدة في Ruby SDK؟

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

## المساهمة

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