Skip to main content
يوفّر Java SDK لتطبيقات Java وصولًا مهيكلًا إلى REST API الخاص بـ Dodo Payments. ويستخدم أنواع Java في جميع أجزائه: Optional للحقول التي قد تكون مفقودة، وStream لتكرار النتائج، وCompletableFuture للاستدعاءات غير المتزامنة.

التثبيت

Maven

أضف التبعية إلى pom.xml:
pom.xml

Gradle

أضف التبعية إلى build.gradle.kts الخاص بك:
build.gradle.kts
تضيف إصدارات SDK دعمًا لتغييرات API. للعثور على أحدث إصدار، راجع Maven Central.
يتطلب SDK إصدار Java 8 أو أحدث، ولذلك يعمل أيضًا على Java 11 و17 و21.

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

أنشئ عميلًا، ثم أنشئ جلسة Checkout:
يتصل fromEnv() بالوضع المباشر ما لم يحدّد DODO_PAYMENTS_BASE_URL أو dodopayments.baseUrl خلاف ذلك. لاستخدام وضع الاختبار، راجع وضع الاختبار. يعمل مفتاح API الخاص بوضع الاختبار في وضع الاختبار فقط.
احتفظ بمفاتيح API في متغيرات البيئة أو خصائص النظام أو مدير الأسرار. لا تضعها أبدًا بشكل ثابت في الكود المصدري.

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

Type Safety

فئات typed للطلبات والاستجابات لإجراء عمليات التحقق أثناء compile time.

Shared Client

أنشئ عميلًا واحدًا وأعد استخدامه عبر الطلبات: فهو يحتفظ بمجموعات الاتصالات وthread pools. كائنات الطلب والاستجابة غير قابلة للتغيير.

Builder Pattern

تحتوي كل فئة طلب على builder، ويُنشئ toBuilder() نسخة معدّلة.

Async Support

يعيد client.async() عميلًا تُرجع أساليبه CompletableFuture.

الإعدادات

متغيرات البيئة

يقرأ fromEnv() متغيرات البيئة هذه أو خصائص النظام المطابقة لها. تكون الأولوية لخصائص النظام:
.env
يأتي مفتاح API من 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:
يعيد العميل المحاولة مرتين افتراضيًا وتنتهي مهلة الانتظار بعد دقيقة واحدة. ويعيد المحاولة عند أخطاء الاتصال والاستجابات ذات status 408 أو 409 أو 429 أو 500 فأعلى. لتجاوز مهلة الانتظار لاستدعاء واحد، مرّر 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، ثم استرجعه باستخدام المعرّف:

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

أنشئ اشتراكًا باستخدام رابط دفع، ثم نفّذ عملية تحصيله إذا كان اشتراكًا عند الطلب.
إن POST /subscriptions (وهو أسلوب subscriptions().create() الخاص بـ SDK) deprecated. لا يزال يعمل مع عمليات التكامل الحالية، لكن ينبغي لعمليات التكامل الجديدة إنشاء الاشتراكات من خلال جلسة Checkout.
تكون قيمة productPrice بوحدة العملة الأصغر، مثل السنتات بالنسبة إلى USD أو البايسات بالنسبة إلى INR. لتحصيل $25.00، مرّر 2500.
يُستخدم subscriptions().charge(...) مع الاشتراكات عند الطلب. يتولى Dodo Payments إصدار فواتير الاشتراكات الأخرى تلقائيًا وفق جدول فوترة المنتج.

الفوترة القائمة على الاستخدام

إعداد العدادات

أنشئ عدادًا يحصي الأحداث، ثم اعرض قائمة العدادات. يكرّر autoPager() عبر كل عداد ويجلب صفحات إضافية عند الحاجة:

إدخال أحداث الاستخدام

أرسل حدث استخدام لعميل. تكون قيم metadata الخاصة بالحدث كائنات JsonValue:
يُعد eventId مفتاح idempotency، لذا امنح كل حدث قيمة فريدة. يُرفض حدث timestamp إذا كان أقدم من ساعة واحدة أو يقع بعد أكثر من 5 دقائق في المستقبل.

إدخال الأحداث دفعة واحدة

أرسل ما يصل إلى 1,000 حدث في طلب واحد. يستخدم هذا المثال imports من المثال السابق:

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

يرمي SDK استثناءات غير محددة. عند حدوث status خطأ، يرمي فئة فرعية من DodoPaymentsServiceException، التي تحتوي على statusCode() وheaders() وbody(). التقط الفئات المحددة التي تريد التعامل معها قبل الفئة الأساسية:
تؤدي حالات status التي لا تملك فئة خاصة بها، مثل 409، إلى رمي UnexpectedStatusCodeException. تؤدي أعطال الشبكة إلى رمي DodoPaymentsIoException، بينما تؤدي الاستجابات التي لا يستطيع SDK تفسيرها إلى رمي DodoPaymentsInvalidDataException. وترث جميع هذه الفئات من DodoPaymentsException.
يعيد SDK المحاولة عند أخطاء الاتصال والاستجابات ذات status 408 أو 409 أو 429 أو 500 فأعلى، وذلك مرتين افتراضيًا، مع exponential backoff.

العمليات غير المتزامنة

استدعِ async() على العميل للحصول على عميل غير متزامن. وتعيد أساليبه CompletableFuture:
لإنشاء عميل غير متزامن منذ البداية، استخدم DodoPaymentsOkHttpClientAsync.fromEnv().

التكامل مع Spring Boot

فئة الإعداد

سجّل عميلًا واحدًا باعتباره bean، واختر البيئة من خاصية:

طبقة الخدمة

احقن العميل في خدمة:

الموارد

GitHub Repository

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

API Reference

كل endpoint وparameter واستجابة.

Discord Community

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

Report Issues

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

الدعم

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

المساهمة

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