context.Context، وتستخدم معلمات الطلب غلاف Field يفصل بين القيم الصفرية والحقول التي لم يتم تضمينها، ويمكنك إضافة middleware إلى كل طلب.
التثبيت
أضف الوحدة إلى مشروعك:يتطلب SDK الإصدار Go 1.22 أو إصدارًا أحدث.
البداية السريعة
أنشئ عميلًا، ثم أنشئ جلسة checkout:option.WithBearerToken، فإن NewClient يقرأ متغير البيئة DODO_PAYMENTS_API_KEY. وإذا حذفت option.WithEnvironmentTestMode()، يتصل العميل بوضع live. يعمل مفتاح API الخاص بوضع test في وضع test فقط.
الميزات الأساسية
Context Support
تتطلب كل طريقة وسيط
context.Context للإلغاء وتحديد المهلات.Strong Typing
معلمات طلب وstructs استجابة مكتوبة الأنواع لإجراء عمليات التحقق وقت الترجمة.
Middleware
أضف middleware باستخدام
option.WithMiddleware للتسجيل والمقاييس والمنطق المخصص.Goroutine Safe
شارك عميلًا واحدًا بين goroutines.
الإعدادات
يقرأNewClient من البيئة كلًا من DODO_PAYMENTS_API_KEY وDODO_PAYMENTS_WEBHOOK_KEY (سر توقيع webhook الخاص بك) وDODO_PAYMENTS_BASE_URL. وتتجاوزها الخيارات التي تمررها، مثل option.WithBearerToken وoption.WithWebhookKey وoption.WithBaseURL.
للتحقق من webhook، مرّر نص الطلب الخام والعناوين إلى client.Webhooks.Unwrap(rawBody, r.Header). ويتحقق من التوقيع باستخدام مفتاح webhook الخاص بك ويعيد الحدث المُحلَّل. أما client.Webhooks.UnsafeUnwrap(rawBody) فيحلّل النص دون التحقق منه، لذا استخدمه للاختبار فقط. راجع Webhooks.
تستخدم الأمثلة في هذه الصفحة client من البدء السريع.
Context والمهلات
لا تنتهي مهلة الطلبات افتراضيًا. يحدّ موعد نهائي في context من مدة الاستدعاء بالكامل، بما في ذلك عمليات إعادة المحاولة. ولتحديد مهلة كل محاولة، أضفoption.WithRequestTimeout():
إعداد إعادة المحاولة
يعيد SDK المحاولة عند حدوث أخطاء في الاتصال وعند الاستجابات ذات status 408 أو 409 أو 429 أو 500 وما فوق. ويعيد المحاولة مرتين افتراضيًا، مع exponential backoff. عيّنoption.WithMaxRetries على العميل أو على طلب واحد:
العمليات الشائعة
تستخدم الأمثلة في هذا القسم أيضًا context، مثلctx := context.Background().
إنشاء جلسة Checkout
أنشئ جلسة checkout، ثم أعد توجيه العميل إلىCheckoutURL المُعاد:
إدارة العملاء
أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرده باستخدام المعرّف. وتستخدم قيم Metadata أنواع الاتحاد من حزمةshared:
التعامل مع الاشتراكات
أنشئ اشتراكًا، واشحن اشتراكًا عند الطلب، واقرأ سجل استخدام الاشتراك.لا يتطلب
Billing سوى Country، وهو رمز بلد ISO مكوّن من حرفين. أما Customer فهو CustomerRequestUnionParam: مرّر AttachExistingCustomerParam{CustomerID: ...} لعميل موجود، أو NewCustomerParam{Email: ..., Name: ...} لإنشاء عميل. ويُستخدم Charge مع الاشتراكات عند الطلب، بينما يكون ProductPrice بأصغر وحدة للعملة. يعيد GetUsageHistory صفحة واحدة من النتائج، بينما يتكرر GetUsageHistoryAutoPaging عبر كل الصفحات.الفوترة القائمة على الاستخدام
إدخال أحداث الاستخدام
أرسل أحداث الاستخدام إلى عميل:يُعد
EventID مفتاح idempotency، لذا امنح كل حدث قيمة فريدة. إذا ظهر EventID نفسه مرتين في طلب واحد، فسيُرفض الطلب بأكمله. وإذا كان EventID قد أُدخل مسبقًا، فسيتم تجاهل الحدث الجديد. يقبل الطلب ما يصل إلى 1,000 حدث. ويأخذ Timestamp الوقت الحالي افتراضيًا، ويُرفض إذا كان أقدم من ساعة واحدة أو أحدث من 5 دقائق في المستقبل.سرد أحداث الاستخدام
اسرد الأحداث التي تمت تصفيتها حسب العميل واسم الحدث:List صفحة واحدة. وللتكرار عبر كل الصفحات، استدعِ client.UsageEvents.ListAutoPaging(ctx, params) وكرّر باستخدام iter.Next() وiter.Current() وiter.Err(). وتحتوي طرق السرد الأخرى على صيغة AutoPaging نفسها، كما تحتوي كل صفحة على طريقة GetNextPage().
معالجة الأخطاء
عندما يعيد API رمز status غير ناجح، يعيد SDK خطأً من النوع*dodopayments.Error. ويحتوي هذا الخطأ على StatusCode و*http.Request و*http.Response، بالإضافة إلى JSON لنص الخطأ. استخدم errors.As لفحصه، وتفرّع استنادًا إلى StatusCode للتعامل مع حالات محددة:
*url.Error يغلف *net.OpError. يعيد apiErr.DumpRequest(true) الطلب المتسلسل.
Middleware
أضف middleware باستخدامoption.WithMiddleware. يستقبل middleware كل طلب ودالة next التي ترسله:
option.WithMiddleware واحد من اليسار إلى اليمين. ويعمل middleware المُمرَّر إلى NewClient قبل middleware المُمرَّر إلى طلب واحد.
التزامن
العميل آمن للاستخدام المتزامن، لذا يمكنك مشاركة عميل واحد بين goroutines:الموارد
GitHub Repository
الشيفرة المصدرية والإصدارات والقائمة الكاملة للطرق.
API Reference
كل endpoint ومعلمة واستجابة.
Discord Community
اطرح الأسئلة وتحدث مع المطورين الآخرين.
Report Issues
أبلغ عن الأخطاء أو اطلب ميزات جديدة.
الدعم
للحصول على المساعدة بشأن Go SDK:- Discord: انضم إلى خادم المجتمع للحصول على مساعدة فورية.
- البريد الإلكتروني: تواصل مع support@dodopayments.com.
- GitHub: افتح issue في المستودع.