Skip to main content
يوفّر Go SDK لتطبيقات Go وصولًا مكتوب الأنواع إلى REST API الخاص بـ Dodo Payments. تتطلب كل طريقة وسيط context.Context، وتستخدم معلمات الطلب غلاف Field يفصل بين القيم الصفرية والحقول التي لم يتم تضمينها، ويمكنك إضافة middleware إلى كل طلب.

التثبيت

أضف الوحدة إلى مشروعك:
لتثبيت إصدار محدد:
يتطلب SDK الإصدار Go 1.22 أو إصدارًا أحدث.

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

أنشئ عميلًا، ثم أنشئ جلسة checkout:
إذا حذفت option.WithBearerToken، فإن NewClient يقرأ متغير البيئة DODO_PAYMENTS_API_KEY. وإذا حذفت option.WithEnvironmentTestMode()، يتصل العميل بوضع live. يعمل مفتاح API الخاص بوضع test في وضع test فقط.
احتفظ بمفاتيح API في متغيرات البيئة أو في مدير أسرار. لا تضعها مطلقًا بشكل ثابت في الشيفرة المصدرية.

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

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 المُعاد:
يعمل كل عنوان URL لـ checkout مرة واحدة وينتهي بعد 24 ساعة. راجع Checkout Sessions للاطلاع على كل خيار من خيارات الجلسة.

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

أنشئ عميلًا باستخدام عنوان بريد إلكتروني واسم، ثم استرده باستخدام المعرّف. وتستخدم قيم Metadata أنواع الاتحاد من حزمة shared:

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

أنشئ اشتراكًا، واشحن اشتراكًا عند الطلب، واقرأ سجل استخدام الاشتراك.
POST /subscriptions (طريقة Subscriptions.New في SDK) مهملة. وما تزال تعمل مع عمليات الدمج الحالية، لكن ينبغي لعمليات الدمج الجديدة إنشاء الاشتراكات من خلال Checkout Session.
لا يتطلب 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 للتعامل مع حالات محددة:
تُعاد الأخطاء الأخرى دون تغليف. فعلى سبيل المثال، إذا فشل HTTP transport، فقد تتلقى *url.Error يغلف *net.OpError. يعيد apiErr.DumpRequest(true) الطلب المتسلسل.

Middleware

أضف middleware باستخدام option.WithMiddleware. يستقبل middleware كل طلب ودالة next التي ترسله:
تُشغّل عدة middleware في استدعاء option.WithMiddleware واحد من اليسار إلى اليمين. ويعمل middleware المُمرَّر إلى NewClient قبل middleware المُمرَّر إلى طلب واحد.

التزامن

العميل آمن للاستخدام المتزامن، لذا يمكنك مشاركة عميل واحد بين goroutines:

الموارد

GitHub Repository

الشيفرة المصدرية والإصدارات والقائمة الكاملة للطرق.

API Reference

كل endpoint ومعلمة واستجابة.

Discord Community

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

Report Issues

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

الدعم

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

المساهمة

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