> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# نموذج أسترو الأساسي

> ابدأ بسرعة مع نموذج أسترو الأساسي لدينا لدمج مدفوعات دودي في تطبيق أسترو الخاص بك

## نظرة عامة

يوفر نموذج أسترو الأساسي نقطة انطلاق جاهزة للاستخدام لدمج مدفوعات دودي مع تطبيق أسترو الخاص بك. يتضمن هذا القالب جلسات الدفع، ومعالجة الويب هوك، وبوابة العملاء، ومكونات واجهة المستخدم الحديثة لمساعدتك في البدء في قبول المدفوعات بسرعة.

<Info>
  يستخدم هذا الهيكل الأساسي Astro 5 مع TypeScript وTailwind CSS 4، وموصل `@dodopayments/astro`.
</Info>

### الميزات

* **Quick Setup** - ابدأ خلال أقل من 5 دقائق
* **Payment Integration** - تدفق الدفع مُعد مسبقًا باستخدام `@dodopayments/astro`
* **Modern UI** - صفحة تسعير نظيفة ذات سمة داكنة باستخدام Tailwind CSS
* **Webhook Handler** - نقطة نهاية جاهزة للاستخدام لمعالجة أحداث الدفع
* **Customer Portal** - إدارة الاشتراكات بنقرة واحدة
* **TypeScript** - مُطبّق بالكامل مع أنواع قليلة ومركّزة
* **Pre-filled Checkout** - يوضح كيفية تمرير بيانات العميل لتحسين تجربة المستخدم

## المتطلبات المسبقة

قبل أن تبدأ، تأكد من أن لديك:

* **إصدار Node.js LTS** (مطلوب لأسترو 5)
* **حساب مدفوعات دودي** (للوصول إلى مفاتيح API وWebhook من لوحة التحكم)

## بدء سريع

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
    cd dodo-astro-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    سجّل في [Dodo Payments](https://dodopayments.com/) واحصل على بيانات اعتمادك من لوحة التحكم:

    * **مفتاح API:** [لوحة التحكم → المطور → مفاتيح API](https://app.dodopayments.com/developer/api-keys)
    * **مفتاح ويب هوك:** [لوحة التحكم → المطور → ويب هوكس](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      تأكد من أنك في **وضع الاختبار** أثناء التطوير!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    أنشئ ملف `.env` في الدليل الجذري:

    ```bash theme={null}
    cp .env.example .env
    ```

    قم بتحديث القيم باستخدام بيانات اعتماد مدفوعات دودي الخاصة بك:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:4321/
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      لا تقم مطلقًا بإضافة ملف `.env` إلى نظام التحكم في الإصدارات. إنه مضمن بالفعل في `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    حدّث `src/lib/products.ts` بمعرّفات المنتج الفعلية من Dodo Payments:

    ```typescript theme={null}
    export const products: Product[] = [
      {
        product_id: "pdt_001", // Replace with your product ID
        name: "Basic Plan",
        description: "Get access to basic features and support",
        price: 9999, // in cents
        features: [
          "Access to basic features",
          "Email support",
          "1 Team member",
          "Basic analytics",
        ],
      },
      // ... add more products
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    افتح [http://localhost:4321](http://localhost:4321) لمعاينة صفحة التسعير الخاصة بك!
  </Step>
</Steps>

## هيكل المشروع

```text theme={null}
src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind
```

## التخصيص

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

حرّر `src/lib/products.ts` لتعديل:

* معرّفات المنتج (من لوحة Dodo)
* التسعير
* الميزات
* الوصف

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

في `src/components/ProductCard.astro`، استبدل القيم الثابتة ببيانات المستخدم الفعلية الخاصة بك:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### تحديث بوابة العملاء

في `src/components/Header.astro`، استبدل معرّف العميل الثابت بالمعرّف الفعلي من نظام المصادقة أو قاعدة البيانات الخاصة بك:

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

يمكنك إكمال عملية شراء تجريبية للحصول على معرف العميل للاختبار.

## أحداث الويب هوك

يُظهر هذا الهيكل الأساسي كيفية معالجة أحداث الويب هوك في `src/pages/api/webhook.ts`:

* `onSubscriptionActive` - يتم تفعيله عندما يصبح الاشتراك نشطًا

* `onSubscriptionCancelled` - يتم تفعيله عند إلغاء الاشتراك

* `onSubscriptionActive` - يتم تفعيله عندما يصبح الاشتراك نشطًا

* `onSubscriptionCancelled` - يتم تفعيله عندما يتم إلغاء الاشتراك

أضف منطق عملك داخل هذه المعالجات:

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

أضف المزيد من أحداث الويب هوك حسب الحاجة.

للتطوير المحلي، يمكنك استخدام أدوات مثل [ngrok](https://ngrok.com/) لإنشاء نفق آمن إلى خادمك المحلي واستخدامه كعنوان URL للويب هوك الخاص بك.

## النشر

يستخدم هذا النموذج مخرجات ثابتة مع تقديم عند الطلب لمسارات API. ستحتاج إلى تثبيت محول لمنصة النشر الخاصة بك:

| المنصة     | الدليل                                                                      |
| ---------- | --------------------------------------------------------------------------- |
| Vercel     | [نشر على Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [نشر على Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [نشر على Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

راجع [أدلة نشر أسترو](https://docs.astro.build/en/guides/deploy/) لجميع المنصات.

### تحديث عنوان URL للويب هوك

بعد النشر، قم بتحديث عنوان URL للويب هوك في [لوحة تحكم مدفوعات دودي](https://app.dodopayments.com/developer/webhooks):

```text theme={null}
https://your-domain.com/api/webhook
```

تذكّر أيضًا تحديث المتغير البيئي `DODO_PAYMENTS_WEBHOOK_KEY` في بيئة الإنتاج لتطابق مفتاح توقيع الويب هوك الخاص بالنطاق المنشور.

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

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    احذف `node_modules` وأعد تثبيت تبعيات المشروع:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **الأسباب الشائعة:**

    * معرّف منتج غير صالح - تأكد من وجوده في لوحة Dodo
    * مفتاح API أو إعداد بيئة خاطئ في `.env`
    * تفقد وحدة تحكم المتصفح والجهاز الطرفي بحثًا عن أخطاء
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    لاختبار محلي، استخدم [ngrok](https://ngrok.com) لكشف الخادم الخاص بك:

    ```bash theme={null}
    ngrok http 4321
    ```

    حدّث عنوان URL الخاص بالويب هوك في [لوحة Dodo](https://app.dodopayments.com/developer/webhooks) ليكون عنوان ngrok. تذكّر تحديث ملف .env بالمفتاح الصحيح للتحقق من الويب هوك.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    استبدل `CUSTOMER_ID` الثابت بمعرّف عميل فعلي من لوحة Dodo.

    أو دمج نظام المصادقة وقاعدة البيانات لديك لجلب معرّف العميل ديناميكيًا.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    يستخدم هذا الهيكل الأساسي مخرجات ثابتة مع مسارات API عند الطلب. تحتاج إلى تثبيت موصل للنشر:

    راجع [أدلة نشر Astro](https://docs.astro.build/en/guides/deploy/) للحصول على التفاصيل.
  </Accordion>
</AccordionGroup>

## تعرف على المزيد

* [توثيق Dodo Payments](https://docs.dodopayments.com/)
* [توثيق جلسات الخروج](https://docs.dodopayments.com/developer-resources/checkout-session)
* [توثيق Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## الدعم

تحتاج إلى مساعدة بشأن النموذج؟

* انضم إلى [مجتمع Discord](https://discord.gg/bYqAp4ayYh) لطرح الأسئلة والمناقشات
* تحقق من [مستودع GitHub](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) للمشكلات والتحديثات
* اتصل بفريق [الدعم](mailto:support@dodopayments.com) لدينا للحصول على المساعدة