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 الخاص بوضع الاختبار في وضع الاختبار فقط.
الميزات الأساسية
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 المُرجع:
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرجعه باستخدام المعرّف:Customers.Retrieve المعرّف أيضًا كسلسلة نصية، مثل client.Customers.Retrieve("cus_123").
التعامل مع الاشتراكات
أنشئ اشتراكًا، ثم افرض رسومًا عليه إذا كان اشتراكًا عند الطلب.يتطلب
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
الموارد
NuGet Package
إصدارات الحزمة وأوامر التثبيت.
GitHub Repository
التعليمات البرمجية المصدرية والإصدارات والأمثلة.
API Reference
كل نقطة نهاية وكل مَعلمة وكل استجابة.
Discord Community
اطرح الأسئلة وتحدث مع المطورين الآخرين.
الدعم
للحصول على المساعدة بشأن C# SDK:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل عبر support@dodopayments.com.
- GitHub: افتح مشكلة في المستودع.