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

التثبيت

أضف الجوهرة إلى ملف Gemfile الخاص بك:
Gemfile
gem "dodopayments", "~> 1.61.5"
استخدم دائمًا أحدث إصدار من SDK للوصول إلى أحدث ميزات مدفوعات دودي. قم بتشغيل bundle update dodopayments بانتظام للبقاء على اطلاع.
ثم قم بتشغيل:
bundle install
يدعم SDK روبي 3.2.0 والإصدارات الأحدث، مع أنواع شاملة، ومعالجة الأخطاء، وآليات إعادة المحاولة.

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

قم بتهيئة العميل وإنشاء جلسة دفع:
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)
قم بتخزين مفاتيح API الخاصة بك بشكل آمن باستخدام متغيرات البيئة. لا تقم أبدًا بالتزامها في التحكم في الإصدارات أو كشفها في كودك.

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

تقاليد روبي

يتبع تقاليد التسمية في روبي وأنماطها الاصطلاحية

بنية أنيقة

واجهة برمجة تطبيقات نظيفة وقابلة للقراءة تشعر بأنها طبيعية لمطوري روبي

الترقيم التلقائي

مكررات الترقيم التلقائي المدمجة للاستجابات القائمة

أمان النوع

أنواع Sorbet الاختيارية لتعزيز أمان النوع

التكوين

تكوين المهلة

قم بتكوين مهلات الطلبات:
# 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: 0}],
  request_options: {timeout: 5}
)

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

قم بتكوين سلوك إعادة المحاولة التلقائي:
# 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: 0}],
  request_options: {max_retries: 5}
)

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

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

قم بإنشاء جلسة دفع:
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.url

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

قم بإنشاء واسترجاع معلومات العملاء:
# Create a customer
customer = dodo_payments.customers.create(
  email: "[email protected]",
  name: "John Doe",
  metadata: {
    user_id: "12345"
  }
)

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

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

قم بإنشاء وإدارة الاشتراكات المتكررة:
# Create a subscription
subscription = dodo_payments.subscriptions.create(
  customer_id: "cus_123",
  product_id: "prod_456",
  price_id: "price_789"
)

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

# Cancel subscription
dodo_payments.subscriptions.cancel(subscription.id)

الترقيم

الترقيم التلقائي

قم بالتكرار تلقائيًا عبر جميع الصفحات:
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

الترقيم اليدوي

للحصول على مزيد من التحكم في الترقيم:
page = dodo_payments.payments.list

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

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

تعامل مع أخطاء واجهة برمجة تطبيقات مدفوعات دودي المختلفة:
begin
  checkout_session = dodo_payments.checkout_sessions.create(
    product_cart: [{product_id: "product_id", quantity: 0}]
  )
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
قم بتنفيذ منطق إعادة المحاولة مع زيادة زمنية للتأخير لأخطاء حد المعدل لضمان تعامل تطبيقك مع السيناريوهات ذات الحجم الكبير بشكل سلس.

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

استخدم Sorbet لمعلمات الطلبات الآمنة من حيث النوع:
# Type-safe using Sorbet RBI definitions
dodo_payments.checkout_sessions.create(
  product_cart: [
    Dodopayments::CheckoutSessionRequest::ProductCart.new(
      product_id: "product_id",
      quantity: 0
    )
  ]
)

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

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

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

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

قم بإجراء طلبات إلى نقاط النهاية غير الموثقة:
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

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

أرسل معلمات غير موثقة:
checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 0}],
  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:
require "dodopayments"

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

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

قم بإنشاء خدمة دفع:
# 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 الخاصة بك:
# app/controllers/checkouts_controller.rb
class CheckoutsController < ApplicationController
  def create
    service = PaymentService.new
    session = service.create_checkout(checkout_params[:items])
    
    redirect_to session.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:
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.url }.to_json
  rescue Dodopayments::Errors::APIError => e
    status 400
    { error: e.message }.to_json
  end
end

الموارد

الدعم

تحتاج إلى مساعدة بشأن SDK روبي؟

المساهمة

نرحب بالمساهمات! تحقق من إرشادات المساهمة للبدء.