Skip to main content
يتيح Ruby SDK لتطبيقات Ruby الوصول إلى REST API الخاص بـ Dodo Payments. يرسل الطلبات باستخدام net/http من المكتبة القياسية ومجمّع اتصالات، ويعيد محاولة الطلبات الفاشلة، ويتعامل مع القوائم المُقسّمة إلى صفحات نيابةً عنك، ويتضمن تعريفات الأنواع بصيغتي RBI وRBS.

التثبيت

أضف الجوهرة إلى ملف Gemfile الخاص بك:
Gemfile
تضيف إصدارات SDK دعمًا لتغييرات API. شغّل bundle update dodopayments بانتظام للبقاء على أحدث إصدار.
ثم ثبّته:
يتطلب SDK الإصدار Ruby 3.2.0 أو إصدارًا أحدث.

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

أنشئ عميلًا، ثم أنشئ جلسة دفع:
إذا حذفت bearer_token، فسيقرأ العميل متغير البيئة DODO_PAYMENTS_API_KEY. وإذا حذفت environment، فسيتصل العميل بالوضع المباشر. يعمل مفتاح API الخاص بوضع الاختبار فقط مع environment: "test_mode".
احتفظ بمفاتيح API في متغيرات البيئة أو في مدير أسرار. لا تضعها أبدًا في نظام التحكم بالإصدارات أو تكشفها في التعليمات البرمجية.

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

Ruby Conventions

أساليب ووسائط مسماة بصيغة Snake_case، مع قبول التجزئات العادية للوسائط المتداخلة.

Elegant Syntax

الاستجابات عبارة عن كائنات تحتوي على قارئات للسمات، كما أن obj[:prop] يقرأ أيضًا الحقول التي لا يعرّفها SDK.

Auto-Pagination

يتكرر auto_paging_each على كل عنصر ويجلب الصفحة التالية عند الحاجة.

Type Safety

تعريفات RBI لـ Sorbet، من دون اعتماد على sorbet-runtime.

الإعدادات

يقبل Dodopayments::Client.new الوسائط bearer_token وwebhook_key وenvironment وbase_url وmax_retries وtimeout وinitial_retry_delay وmax_retry_delay. عند حذفها، يقرأ DODO_PAYMENTS_API_KEY وDODO_PAYMENTS_WEBHOOK_KEY (سر توقيع webhook الخاص بك) وDODO_PAYMENTS_BASE_URL من البيئة. العميل آمن للاستخدام مع الخيوط ويحتفظ بمجمّع اتصالات خاص به، لذا أنشئ عميلًا واحدًا لتطبيقك وأعد استخدامه. للتحقق من webhook، مرّر نص الطلب الخام والعناوين إلى dodo_payments.webhooks.unwrap(payload, headers: headers). يتحقق من التوقيع باستخدام مفتاح webhook الخاص بك ويعيد الحدث الذي تم تحليله. تعمل dodo_payments.webhooks.unsafe_unwrap(payload) على تحليل النص من دون التحقق منه، لذا استخدمها للاختبار فقط. راجع Webhooks.

إعداد مهلة الانتظار

تنتهي مهلة الطلبات بعد 60 ثانية افتراضيًا. عيّن timeout، بالثواني، على العميل أو على طلب واحد:
عند انتهاء مهلة الطلب، يرفع SDK الاستثناء Dodopayments::Errors::APITimeoutError. يُعاد尝اولة الطلبات التي انتهت مهلتها افتراضيًا.

إعداد إعادة المحاولة

يعيد SDK محاولة أخطاء الاتصال ومهلات الانتظار والاستجابات ذات الحالات 408 و409 و429 و500 وما فوق. يعيد المحاولة مرتين افتراضيًا، مع تراجع أُسّي قصير. عيّن max_retries على العميل أو على طلب واحد:

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

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

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

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

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

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

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

أنشئ اشتراكًا، وحمّل رسوم اشتراك عند الطلب، وحدّث البيانات الوصفية لاشتراك.
POST /subscriptions (أسلوب subscriptions.create في SDK) مهمل. لا يزال يعمل مع عمليات التكامل الحالية، ولكن ينبغي لعمليات التكامل الجديدة إنشاء الاشتراكات من خلال جلسة دفع.
يتطلب billing فقط country، وهو رمز بلد ISO مكوّن من حرفين. يقبل customer { customer_id: "..." } لإرفاق عميل موجود أو { email: "...", name: "..." } لإنشاء عميل. يُستخدم charge مع الاشتراكات عند الطلب، بينما يُعبّر product_price عن أصغر وحدة للعملة.

الترقيم إلى صفحات

الترقيم التلقائي إلى صفحات

تعيد أساليب القائمة صفحةً واحدة. اقرأ items للصفحة الحالية، أو استدعِ auto_paging_each للتكرار على كل عنصر. إذ يجلب الصفحة التالية عند الحاجة:

الترقيم اليدوي إلى صفحات

للانتقال صفحةً واحدة في كل مرة، استدعِ next_page? وnext_page:

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

عندما يتعذر على SDK الاتصال بـ API، أو يعيد API حالة 4xx أو 5xx، يرفع SDK فئة فرعية من Dodopayments::Errors::APIError:
تعتمد فئة الخطأ على السبب. يحتوي كل خطأ على سمات status وheaders وbody:
يعيد SDK بالفعل محاولة استجابات 429 مع تراجع أُسّي. يعني RateLimitError أن عمليات إعادة المحاولة هذه فشلت أيضًا، لذا انتظر مدة أطول قبل إرسال الطلب مجددًا.

أمان الأنواع باستخدام Sorbet

يتضمن SDK تعريفات RBI ولا يعتمد على sorbet-runtime. للحصول على فحص للأنواع في وسائط الطلب، مرّر فئات النماذج بدلًا من التجزئات:

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

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

لاستدعاء نقطة نهاية لا تملك أسلوبًا في SDK، استخدم request. إذ يطبّق المصادقة وعمليات إعادة المحاولة نفسها المستخدمة في أساليب SDK:

الوسائط غير الموثقة

لإرسال وسائط لا يعرّفها SDK، مرّرها في request_options. يتجاوز وسيط extra_* الذي يحمل الاسم نفسه كوسيط موثّق ذلك الوسيط الموثّق:

التكامل مع Rails

إنشاء Initializer

أنشئ عميلًا واحدًا عند بدء Rails، في config/initializers/dodo_payments.rb:

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

غلّف العميل في كائن خدمة:

التكامل مع Controller

استدعِ الخدمة من Controller وأعد التوجيه إلى صفحة الدفع:

التكامل مع Sinatra

أنشئ العميل مرة واحدة في كتلة configure واستخدمه في المسارات:

الموارد

GitHub Repository

الشيفرة المصدرية والإصدارات والقائمة الكاملة للأساليب.

API Reference

كل نقطة نهاية ووسيط واستجابة.

Discord Community

اطرح الأسئلة وتحدث مع المطورين الآخرين.

Report Issues

أبلغ عن الأخطاء أو اطلب ميزات جديدة.

الدعم

للحصول على المساعدة بشأن Ruby SDK:

المساهمة

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