Skip to main content
يوفّر C# SDK لتطبيقات .NET وصولًا مكتوبًا إلى REST API الخاص بـ Dodo Payments. كل طريقة API غير متزامنة وتُرجع Task، كما أن الطلبات والاستجابات عبارة عن فئات مكتوبة، ويعيد العميل محاولة الطلبات الفاشلة نيابةً عنك.

التثبيت

ثبّت الحزمة من NuGet:
يتطلب SDK الإصدار .NET Standard 2.0 أو إصدارًا أحدث، كما يتوفر أيضًا بإصدار مخصص لـ .NET 8. وهو يعمل مع ASP.NET Core وتطبيقات وحدة التحكم وأنواع مشاريع .NET الأخرى. تستخدم الأمثلة في هذه الصفحة صياغة C# 12، مثل تعبيرات المجموعات.

البدء السريع

أنشئ عميلًا، ثم أنشئ جلسة دفع:
إذا لم تُعيّن BearerToken، فسيقرأ العميل متغير البيئة DODO_PAYMENTS_API_KEY. وإذا لم تُعيّن BaseUrl أو DODO_PAYMENTS_BASE_URL، فسيتصل العميل بالوضع المباشر. لاستخدام وضع الاختبار، راجع البيئات. يعمل مفتاح API الخاص بوضع الاختبار في وضع الاختبار فقط.
احتفظ بمفاتيح API في متغيرات البيئة أو أسرار المستخدم أو Azure Key Vault. لا تضعها في التعليمات البرمجية المصدرية بشكل ثابت، ولا ترفعها إلى نظام التحكم في الإصدارات.

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

Async/Await

تُرجع كل طريقة API قيمة Task وتقبل CancellationToken اختياريًا.

Strong Typing

فئات مكتوبة للطلبات والاستجابات، مع تعليقات توضيحية لأنواع المراجع القابلة للقيمة الفارغة.

Smart Retries

محاولتا إعادة افتراضيًا، مع تأخير متزايد أُسّيًا، لأخطاء الاتصال ورموز الحالة القابلة لإعادة المحاولة.

Error Handling

فئة استثناء لكل خطأ HTTP شائع، مع رمز الحالة ونص الاستجابة.

الإعدادات

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

خزّن مفتاح API في متغير بيئة:
.env
يقرأ العميل الذي تم إنشاؤه باستخدام new() إعداداته من البيئة:
يقرأ العميل متغيرات البيئة التالية عندما لا تُعيّن الخاصية المطابقة: إذا لم يتم تعيين BearerToken ولا DODO_PAYMENTS_API_KEY، فسيطرح العميل DodoPaymentsInvalidDataException. يحتوي WebhookKey على سر توقيع webhook، لكن C# SDK لا يتضمن طريقة للتحقق من توقيعات webhook. للتحقق منها، اتبع Webhooks.

الإعداد اليدوي

عيّن الخصائص على العميل لتجاوز متغيرات البيئة:

البيئات

يتصل العميل بالوضع المباشر (https://live.dodopayments.com) افتراضيًا. لاستخدام وضع الاختبار (https://test.dodopayments.com)، عيّن BaseUrl إلى EnvironmentUrl.TestMode:

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

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

مهلات الانتظار

تنتهي مهلة كل محاولة طلب بعد دقيقة واحدة افتراضيًا. ولا تشمل المهلة محاولات إعادة المحاولة. عيّن Timeout لتغييرها:

التجاوزات لكل طلب

لتغيير الإعدادات لطلب واحد، استدعِ WithOptions على العميل أو على خدمة. ويُرجع نسخة معدّلة تشارك مجموعة اتصالات واحدة، بينما لا يتغير العميل الأصلي:

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

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

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

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

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

أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرجعه باستخدام المعرّف:
يقبل Customers.Retrieve المعرّف أيضًا كسلسلة نصية، مثل client.Customers.Retrieve("cus_123").

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

أنشئ اشتراكًا، ثم افرض رسومًا عليه إذا كان اشتراكًا عند الطلب.
إن POST /subscriptions (طريقة Subscriptions.Create في SDK) مهمل. ولا يزال يعمل مع عمليات الدمج الحالية، لكن ينبغي لعمليات الدمج الجديدة إنشاء الاشتراكات عبر جلسة دفع.
يتطلب Billing فقط Country، وهو رمز دولة ISO مكوّن من حرفين. يأخذ Customer قيمة AttachExistingCustomer لإرفاق عميل موجود أو قيمة NewCustomer لإنشاء عميل. يُستخدم Charge مع الاشتراكات عند الطلب، بينما تكون قيمة ProductPrice بوحدة العملة الأصغر.

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

عندما تُرجع API حالة خطأ، يطرح SDK فئة فرعية من DodoPaymentsApiException، التي تحتوي على الخاصيتين StatusCode وResponseBody. تعتمد فئة الاستثناء على رمز الحالة. وترث جميع استثناءات 4xx من DodoPayments4xxException. تؤدي حالة 4xx التي لا تملك فئة خاصة بها، مثل 409، إلى طرح DodoPayments4xxException. ويتعامل DodoPaymentsUnexpectedStatusCodeException مع الحالات الواقعة خارج نطاقي 4xx و5xx. يطرح SDK أيضًا الاستثناءات التالية:
  • DodoPaymentsIOException: خطأ في الإدخال والإخراج أو في الشبكة.
  • DodoPaymentsInvalidDataException: تعذّر على SDK تفسير بيانات الاستجابة، مثلًا بسبب فقدان خاصية مطلوبة.
  • DodoPaymentsException: الفئة الأساسية لكل استثناءات SDK.

التنقل بين الصفحات

تُرجع طرق القائمة صفحة واحدة من النتائج. ويمكنك التكرار عبر كل عنصر أو التنقل بين الصفحات بنفسك.

التنقل التلقائي بين الصفحات

يُرجع Paginate قيمة IAsyncEnumerable التي تجلب الصفحة التالية عند الحاجة إليها:

التنقل اليدوي بين الصفحات

للعمل مع صفحة واحدة في كل مرة، اقرأ Items، ثم استدعِ HasNext() وNext():
لتعيين حجم الصفحة، مرّر PaymentListParams من مساحة الأسماء DodoPayments.Client.Models.Payments، مثل client.Payments.List(new PaymentListParams { PageSize = 50 }).

التكامل مع ASP.NET Core

سجّل عميلًا واحدًا كعنصر singleton في حاوية حقن الاعتماديات، واقرأ مفتاح API من الإعدادات:
Program.cs
أضف المفتاح إلى إعداداتك، مثلًا في appsettings.json:
appsettings.json
أثناء التطوير، خزّن المفتاح باستخدام أسرار المستخدم بدلًا من تخزينه في appsettings.json:

الموارد

NuGet Package

إصدارات الحزمة وأوامر التثبيت.

GitHub Repository

التعليمات البرمجية المصدرية والإصدارات والأمثلة.

API Reference

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

Discord Community

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

الدعم

للحصول على المساعدة بشأن C# SDK:
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦