Optional للحقول التي قد تكون مفقودة، وStream لتكرار النتائج، وCompletableFuture للاستدعاءات غير المتزامنة.
التثبيت
Maven
أضف التبعية إلىpom.xml:
pom.xml
Gradle
أضف التبعية إلىbuild.gradle.kts الخاص بك:
build.gradle.kts
يتطلب SDK إصدار Java 8 أو أحدث، ولذلك يعمل أيضًا على Java 11 و17 و21.
البداية السريعة
أنشئ عميلًا، ثم أنشئ جلسة Checkout:fromEnv() بالوضع المباشر ما لم يحدّد DODO_PAYMENTS_BASE_URL أو dodopayments.baseUrl خلاف ذلك. لاستخدام وضع الاختبار، راجع وضع الاختبار. يعمل مفتاح API الخاص بوضع الاختبار في وضع الاختبار فقط.
الميزات الأساسية
Type Safety
فئات typed للطلبات والاستجابات لإجراء عمليات التحقق أثناء compile time.
Shared Client
أنشئ عميلًا واحدًا وأعد استخدامه عبر الطلبات: فهو يحتفظ بمجموعات الاتصالات وthread pools. كائنات الطلب والاستجابة غير قابلة للتغيير.
Builder Pattern
تحتوي كل فئة طلب على builder، ويُنشئ
toBuilder() نسخة معدّلة.Async Support
يعيد
client.async() عميلًا تُرجع أساليبه CompletableFuture.الإعدادات
متغيرات البيئة
يقرأfromEnv() متغيرات البيئة هذه أو خصائص النظام المطابقة لها. تكون الأولوية لخصائص النظام:
.env
DODO_PAYMENTS_API_KEY أو dodopayments.apiKey. ويأتي سر توقيع webhook من DODO_PAYMENTS_WEBHOOK_KEY أو dodopayments.webhookKey، بينما يأتي عنوان URL الأساسي من DODO_PAYMENTS_BASE_URL أو dodopayments.baseUrl. أنشئ عميلًا واحدًا وأعد استخدامه، لأن لكل عميل مجموعة اتصالات وthread pools خاصة به.
للتحقق من webhook، مرّر نص الطلب الخام والعناوين إلى client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build())، حيث إن headers هو com.dodopayments.api.core.http.Headers. يتحقق من التوقيع باستخدام مفتاح webhook الخاص بك ويعيد الحدث الذي جرى تحليله، أو يرمي DodoPaymentsWebhookException. عند عدم توفير العناوين، لا يتحقق unwrap من التوقيع. يحلل client.webhooks().unsafeUnwrap(rawBody) النص دون التحقق منه، لذا استخدمه للاختبار فقط. راجع Webhooks.
الإعداد اليدوي
عيّن كل خيار في builder:RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() باعتباره الوسيط الثاني للأسلوب. يتحقق responseValidation(true) مسبقًا من تطابق الاستجابة بأكملها مع الأنواع المتوقعة. وبدونه، يرمي SDK DodoPaymentsInvalidDataException فقط عند قراءة خاصية ذات نوع غير متوقع.
وضع الاختبار
لاستخدام وضع الاختبار (https://test.dodopayments.com)، استدعِ testMode() على builder:
العمليات الشائعة
تستخدم الأمثلة في هذا القسمclient من البدء السريع.
إنشاء جلسة Checkout
أنشئ جلسة Checkout، ثم أعد توجيه العميل إلى عنوان URL الخاص بـ Checkout الذي تم إرجاعه:checkoutUrl() قيمة Optional<String>. يعمل كل عنوان URL الخاص بـ Checkout مرة واحدة وينتهي بعد 24 ساعة. للاطلاع على كل خيار من خيارات الجلسة، راجع جلسات Checkout.
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم وmetadata، ثم استرجعه باستخدام المعرّف:التعامل مع الاشتراكات
أنشئ اشتراكًا باستخدام رابط دفع، ثم نفّذ عملية تحصيله إذا كان اشتراكًا عند الطلب.تكون قيمة
productPrice بوحدة العملة الأصغر، مثل السنتات بالنسبة إلى USD أو البايسات بالنسبة إلى INR. لتحصيل $25.00، مرّر 2500.الفوترة القائمة على الاستخدام
إعداد العدادات
أنشئ عدادًا يحصي الأحداث، ثم اعرض قائمة العدادات. يكرّرautoPager() عبر كل عداد ويجلب صفحات إضافية عند الحاجة:
إدخال أحداث الاستخدام
أرسل حدث استخدام لعميل. تكون قيم metadata الخاصة بالحدث كائناتJsonValue:
eventId مفتاح idempotency، لذا امنح كل حدث قيمة فريدة. يُرفض حدث timestamp إذا كان أقدم من ساعة واحدة أو يقع بعد أكثر من 5 دقائق في المستقبل.
إدخال الأحداث دفعة واحدة
أرسل ما يصل إلى 1,000 حدث في طلب واحد. يستخدم هذا المثال imports من المثال السابق:معالجة الأخطاء
يرمي SDK استثناءات غير محددة. عند حدوث status خطأ، يرمي فئة فرعية منDodoPaymentsServiceException، التي تحتوي على statusCode() وheaders() وbody(). التقط الفئات المحددة التي تريد التعامل معها قبل الفئة الأساسية:
UnexpectedStatusCodeException. تؤدي أعطال الشبكة إلى رمي DodoPaymentsIoException، بينما تؤدي الاستجابات التي لا يستطيع SDK تفسيرها إلى رمي DodoPaymentsInvalidDataException. وترث جميع هذه الفئات من DodoPaymentsException.
العمليات غير المتزامنة
استدعِasync() على العميل للحصول على عميل غير متزامن. وتعيد أساليبه CompletableFuture:
DodoPaymentsOkHttpClientAsync.fromEnv().
التكامل مع Spring Boot
فئة الإعداد
سجّل عميلًا واحدًا باعتباره bean، واختر البيئة من خاصية:طبقة الخدمة
احقن العميل في خدمة:الموارد
GitHub Repository
الكود المصدري والإصدارات والقائمة الكاملة للأساليب.
API Reference
كل endpoint وparameter واستجابة.
Discord Community
اطرح الأسئلة وتحدث مع المطورين الآخرين.
Report Issues
أبلغ عن الأخطاء أو اطلب ميزات جديدة.
الدعم
للحصول على مساعدة بشأن Java SDK:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل مع support@dodopayments.com.
- GitHub: افتح issue في المستودع.