net/http من المكتبة القياسية ومجمّع اتصالات، ويعيد محاولة الطلبات الفاشلة، ويتعامل مع القوائم المُقسّمة إلى صفحات نيابةً عنك، ويتضمن تعريفات الأنواع بصيغتي RBI وRBS.
التثبيت
أضف الجوهرة إلى ملف Gemfile الخاص بك:Gemfile
يتطلب SDK الإصدار Ruby 3.2.0 أو إصدارًا أحدث.
البداية السريعة
أنشئ عميلًا، ثم أنشئ جلسة دفع:bearer_token، فسيقرأ العميل متغير البيئة DODO_PAYMENTS_API_KEY. وإذا حذفت environment، فسيتصل العميل بالوضع المباشر. يعمل مفتاح API الخاص بوضع الاختبار فقط مع environment: "test_mode".
الميزات الأساسية
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، بالثواني، على العميل أو على طلب واحد:
Dodopayments::Errors::APITimeoutError. يُعاد尝اولة الطلبات التي انتهت مهلتها افتراضيًا.
إعداد إعادة المحاولة
يعيد SDK محاولة أخطاء الاتصال ومهلات الانتظار والاستجابات ذات الحالات 408 و409 و429 و500 وما فوق. يعيد المحاولة مرتين افتراضيًا، مع تراجع أُسّي قصير. عيّنmax_retries على العميل أو على طلب واحد:
العمليات الشائعة
تستخدم الأمثلة في هذا القسم العميلdodo_payments من البدء السريع.
إنشاء جلسة دفع
أنشئ جلسة دفع، ثم أعد توجيه العميل إلىcheckout_url المُعاد:
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرجعه باستخدام المعرّف:التعامل مع الاشتراكات
أنشئ اشتراكًا، وحمّل رسوم اشتراك عند الطلب، وحدّث البيانات الوصفية لاشتراك.يتطلب
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:
أمان الأنواع باستخدام 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:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل مع support@dodopayments.com.
- GitHub: افتح issue في المستودع.