قالب Go الجاهز

GitHub Repository

قالب Go + Dodo Payments الجاهز والبسيط

نظرة عامة

إن boilerplate الخاص بـ Go هو خادم Go بسيط يبيع منتجاتك في Dodo Payments من صفحة تسعير. ينشئ جلسات checkout، ويتحقق من webhooks ويعالجها، ويفتح Customer Portal. استنسخه كنقطة بداية لخلفية Go الخاصة بك.

يتطلب boilerplate الإصدار Go 1.24.4 أو أحدث، وهو الإصدار المحدد في go.mod. ويستخدم تخطيطًا يتكون من cmd وinternal وtemplates، ويعرض صفحة التسعير باستخدام قوالب HTML في Go، ويستدعي Dodo Payments API من خلال SDK ‏dodopayments-go.

الميزات

الإعداد السريع: استنسخ المستودع، وأضف مفاتيح API إلى .env، ثم شغّل الخادم باستخدام make run.
تكامل الدفع: تدفق checkout ينشئ جلسات checkout باستخدام SDK ‏dodopayments-go.
واجهة مستخدم عصرية: صفحة تسعير ذات سمة داكنة، مبنية باستخدام قوالب HTML في Go وTailwind CSS.
معالجة Webhook: يتحقق من توقيع كل webhook قبل معالجة الحدث.
Customer Portal: إدارة الاشتراكات ذاتيًا من خلال Customer Portal.
أفضل ممارسات Go: تخطيط مشروع منظم باستخدام cmd وinternal وtemplates.
Checkout مملوء مسبقًا: يمرر اسم العميل وبريده الإلكتروني إلى checkout، حتى لا يضطر العميل إلى إدخالهما مرة أخرى.

المتطلبات الأساسية

قبل البدء، تحتاج إلى:

Go 1.24.4 أو أحدث. تحقق من الإصدار باستخدام go version.
حساب Dodo Payments لإنشاء API key ومفتاح توقيع webhook في لوحة المعلومات.
منتج واحد على الأقل تم إنشاؤه ضمن Products في لوحة المعلومات.

البدء السريع

Clone the Repository

git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate

Install Dependencies

make install

يشغّل make install الأمر go mod download ثم go mod tidy. لتنزيل الوحدات بدون make، شغّل:

go mod download

Get API Credentials

سجّل حسابًا في Dodo Payments، ثم انسخ المفتاحين من لوحة المعلومات:

API Key: Developer → API Keys
Webhook Key: Developer → Webhooks. لكل webhook endpoint مفتاح توقيع خاص به. لإنشاء endpoint يصل إلى خادمك المحلي، راجع اختبار Webhooks محليًا.

أنشئ المفتاحين في وضع الاختبار أثناء التطوير. للتبديل إلى وضع الاختبار، عطّل مفتاح Live Mode في الشريط الجانبي للوحة المعلومات.

Configure Environment Variables

أنشئ ملف .env في جذر المشروع باستخدام القالب:

cp .env.example .env

عيّن هذه القيم في .env:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:8000
DODO_PAYMENTS_ENVIRONMENT=test_mode
PORT=8000

يقرأ الخادم هذه المتغيرات عند بدء التشغيل:

المتغير	مطلوب	القيمة الافتراضية	الغرض
`DODO_PAYMENTS_API_KEY`	نعم	لا شيء	يصادق على الطلبات المرسلة إلى Dodo Payments API.
`DODO_PAYMENTS_WEBHOOK_KEY`	نعم	لا شيء	يتحقق من توقيع webhooks الواردة.
`DODO_PAYMENTS_RETURN_URL`	لا	`http://localhost:8080`	عنوان URL الذي يرسل checkout العميل إليه بعد الدفع.
`DODO_PAYMENTS_ENVIRONMENT`	لا	`test_mode`	`test_mode` أو `live_mode`.
`PORT`	لا	`8000`	المنفذ الذي يستمع إليه الخادم.

يتوقف الخادم عند بدء التشغيل إذا كان أي من المفتاحين المطلوبين مفقودًا. يعيّن .env.example كلًا من PORT وDODO_PAYMENTS_RETURN_URL إلى المنفذ 8080. تستخدم هذه الصفحة المنفذ 8000، لذا عيّن كليهما إلى 8000 كما هو موضح، أو استبدل 8000 بـ 8080 في الأوامر الموجودة في هذه الصفحة.

لا ترفع ملف .env إلى نظام التحكم في الإصدارات. يستبعده .gitignore الموجود في المستودع بالفعل.

Add Your Products

استبدل المنتج النموذجي في internal/lib/products.go بمنتجاتك. انسخ معرّف كل منتج من Products في لوحة المعلومات:

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999, // in cents
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
    // ... add more products
}

يعيّن Price السعر الذي تعرضه صفحة التسعير فقط، بأصغر وحدة للعملة: يعرض 9999 بالشكل $99.99. يفرض checkout سعر المنتج في Dodo Payments.

Run the Development Server

make run

ينشئ make run الخادم داخل bin/server ثم يشغّله. لتشغيل الخادم دون إنشاء ملف ثنائي أولًا، شغّل:

go run cmd/server/main.go

افتح http://localhost:8000 لعرض صفحة التسعير.

سترى صفحة تسعير ذات سمة داكنة تعرض منتجاتك، وتكون جاهزة للشراء.

بنية المشروع

يحتوي المستودع على التخطيط التالي:

go-boilerplate/
├── cmd/
│   └── server/             # Application entry point (main.go)
├── internal/
│   ├── api/                # API handlers: checkout.go, portal.go, webhook.go
│   ├── core/               # Configuration loading (config.go)
│   └── lib/                # Shared logic: products.go, customers.go
├── templates/              # HTML templates: base.html, index.html
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md

API Endpoints

يتضمن boilerplate نقاط النهاية المُعدّة مسبقًا التالية:

نقطة النهاية	الطريقة	الوصف
`/`	GET	صفحة تسعير تعرض المنتجات الموجودة في `internal/lib/products.go`.
`/api/checkout`	POST	ينشئ جلسة checkout. أرسل `product_id`، بالإضافة إلى `quantity` الاختياري (الافتراضي `1`) و`customer` (`email` و`name` و`phone`). يعيد `session_id` و`checkout_url`.
`/api/webhook`	POST	يتحقق من webhooks في Dodo Payments ويعالجها. يعيد `401` عند فشل التحقق من التوقيع.
`/api/customer-portal`	POST	يعيد رابط Customer Portal في `portal_url`. أرسل `customer_id`، أو `email` مع `name` اختياري. عند إرسال البريد الإلكتروني فقط، يبحث المعالج عن العميل وينشئه إذا لم يكن موجودًا.
`/health`	GET	فحص السلامة. يعيد `OK`.

التخصيص

تحديث معلومات المنتج

حرّر internal/lib/products.go لتغيير ما يلي:

معرّفات المنتجات (من Products في لوحة معلومات Dodo Payments الخاصة بك)
الأسماء
الأسعار المعروضة في صفحة التسعير
الميزات
الأوصاف

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}

يضيف قالب صفحة التسعير لاحقة /mo إلى كل سعر، ويعرض Custom بدلًا من السعر عندما تكون قيمة Price هي 100000 أو أكبر. لتغيير ذلك، حرّر templates/index.html.

ملء بيانات العميل مسبقًا

في .env، ترسل الدالة handleCheckout بيانات عميل ثابتة إلى /api/checkout. استبدلها ببيانات المستخدم الذي سجّل دخوله:

const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};

تعيد الدالة handlePortal استخدام بيانات العميل هذه، وتعود إلى الاسم والبريد الإلكتروني النموذجيين نفسيهما. في تطبيق إنتاجي، مرّر هذه القيم من نظام المصادقة لديك إلى كلتا الدالتين.

Webhook Events

يتحقق internal/api/webhook.go من كل طلب باستخدام client.Webhooks.Unwrap والمفتاح الموجود في DODO_PAYMENTS_WEBHOOK_KEY، ثم يوجّه الحدث حسب type الخاص به. لهذه الأحداث معالج، ويسجّل كل معالج بيانات الحدث:

الحدث	الوصف
`payment.succeeded`	يتم تشغيله عند نجاح عملية دفع
`payment.failed`	يتم تشغيله عند فشل محاولة دفع
`subscription.active`	يتم تشغيله عند تنشيط اشتراك
`subscription.renewed`	يتم تشغيله عند تجديد اشتراك لفترة الفوترة التالية
`subscription.updated`	يتم تشغيله عند تغيير أي حقل في الاشتراك
`subscription.cancelled`	يتم تشغيله عند إلغاء اشتراك

يقبل المعالج أيضًا subscription.on_hold وsubscription.failed وsubscription.expired وsubscription.plan_changed دون تنفيذ أي إجراء، ويسجّل كل نوع حدث آخر باعتباره غير مُعالج. ويستجيب بالرمز 200 لكل حدث تم التحقق منه. للاطلاع على جميع أنواع الأحداث، راجع دليل أحداث Webhook. أضف منطق نشاطك التجاري إلى دوال المعالجة من أجل:

تحديث أذونات المستخدمين في قاعدة بياناتك
إرسال رسائل تأكيد بالبريد الإلكتروني
توفير الوصول إلى المنتجات الرقمية
تتبع التحليلات والمقاييس

اختبار Webhooks محليًا

لا يستطيع Dodo Payments الوصول إلى localhost. لتلقي webhooks أثناء التطوير، اكشف خادمك المحلي باستخدام نفق مثل ngrok:

ngrok http 8000

في لوحة معلومات Dodo Payments، أضف endpoint باستخدام عنوان URL لإعادة التوجيه الذي يطبعه ngrok، متبوعًا بـ /api/webhook:

https://your-ngrok-url.ngrok.io/api/webhook

انسخ مفتاح توقيع endpoint إلى DODO_PAYMENTS_WEBHOOK_KEY، ثم أعد تشغيل الخادم.

النشر

الإنشاء للإنتاج

يُجمّع make build الخادم داخل bin/server:

make build

لإنشاء الملف الثنائي وتشغيله دون make، شغّل:

go build -o bin/server cmd/server/main.go
./bin/server

النشر إلى Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) بعد النشر، أضف المتغيرات من ملف .env إلى إعدادات مشروع Vercel، لأن .env غير موجود في المستودع. ثم عيّن webhook endpoint في لوحة المعلومات إلى https://yourdomain.com/api/webhook.

Docker

أنشئ ملف Dockerfile في جذر المشروع. يجب أن تستخدم مرحلة الإنشاء Go 1.24.4 أو أحدث لمطابقة go.mod:

FROM golang:1.24-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]

تنقل الصورة النهائية templates/ إلى جانب الملف الثنائي، لأن الخادم يحمّل القوالب من دليل العمل. أنشئ الصورة وشغّلها:

docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo

يستمع الحاوي إلى قيمة PORT من .env، لذا أبقِ PORT=8000 متطابقًا مع تعيين المنفذ.

اعتبارات الإنتاج

قبل النشر إلى الإنتاج:

عيّن DODO_PAYMENTS_ENVIRONMENT إلى live_mode.
استخدم API key في الوضع المباشر من لوحة المعلومات.
وجّه webhook endpoint إلى نطاق الإنتاج، واستخدم مفتاح توقيع ذلك endpoint.
عيّن DODO_PAYMENTS_RETURN_URL إلى صفحة في نطاق الإنتاج.
قدّم كل endpoint عبر HTTPS.

استكشاف الأخطاء وإصلاحها

Build errors or missing dependencies

تحقق من أن go version يعرض Go 1.24.4 أو أحدث، ثم نزّل الوحدات مرة أخرى:

go mod tidy
go mod download

Checkout session creation fails

الأسباب الشائعة:

معرّف المنتج غير صالح. تحقق من وجوده ضمن Products في الوضع نفسه المستخدم مع API key.
API key أو DODO_PAYMENTS_ENVIRONMENT في .env غير صحيح. يحتاج مفتاح وضع الاختبار إلى test_mode.
لمعرفة الخطأ الدقيق، راجع سجلات الخادم. يسجّل المعالج كل طلب فاشل قبل أن يعيد 500.

Webhooks not receiving events

للاختبار المحلي، اكشف خادمك باستخدام ngrok:

ngrok http 8000

عيّن عنوان URL الخاص بـ webhook في لوحة معلومات Dodo Payments إلى عنوان URL الخاص بـ ngrok. ثم عيّن DODO_PAYMENTS_WEBHOOK_KEY في .env إلى مفتاح توقيع ذلك endpoint. إذا سجّل الخادم webhook verification failed، فهذا يعني أن المفتاح لا يطابق endpoint.

Templates not loading

يحمّل الخادم templates/base.html وtemplates/index.html من دليل العمل. شغّل الخادم من جذر المشروع، أو غيّر مسارات القوالب في cmd/server/main.go.

تعلّم المزيد

Go SDK

توثيق Go SDK الكامل

Webhooks Documentation

تعرّف على جميع أحداث webhook وأفضل الممارسات

Checkout Sessions

تعمّق في إعدادات جلسة checkout

API Reference

توثيق Dodo Payments API الكامل

الدعم

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

اطرح أسئلتك في مجتمع Discord.
راجع مستودع GitHub للاطلاع على المشكلات والتحديثات.
تواصل مع فريق الدعم.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

نظرة عامة

الميزات

المتطلبات الأساسية

البدء السريع

بنية المشروع

API Endpoints

التخصيص

تحديث معلومات المنتج

ملء بيانات العميل مسبقًا

Webhook Events

اختبار Webhooks محليًا

النشر

الإنشاء للإنتاج

النشر إلى Vercel

Docker

اعتبارات الإنتاج

استكشاف الأخطاء وإصلاحها

تعلّم المزيد

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

الدعم

GitHub Repository

​نظرة عامة

​الميزات

​المتطلبات الأساسية

​البدء السريع

​بنية المشروع

​API Endpoints

​التخصيص

​تحديث معلومات المنتج

​ملء بيانات العميل مسبقًا

​Webhook Events

​اختبار Webhooks محليًا

​النشر

​الإنشاء للإنتاج

​النشر إلى Vercel

​Docker

​اعتبارات الإنتاج

​استكشاف الأخطاء وإصلاحها

​تعلّم المزيد

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​الدعم

نظرة عامة

الميزات

المتطلبات الأساسية

البدء السريع

بنية المشروع

API Endpoints

التخصيص

تحديث معلومات المنتج

ملء بيانات العميل مسبقًا

Webhook Events

اختبار Webhooks محليًا

النشر

الإنشاء للإنتاج

النشر إلى Vercel

Docker

اعتبارات الإنتاج

استكشاف الأخطاء وإصلاحها

تعلّم المزيد

الدعم