> ## 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.

# Astro Minimal Boilerplate

> Bắt đầu nhanh chóng với mẫu Astro tối giản của chúng tôi để tích hợp Dodo Payments vào ứng dụng Astro của bạn

## Tổng quan

Mẫu Astro tối giản cung cấp một điểm khởi đầu sẵn sàng để tích hợp Dodo Payments với ứng dụng Astro của bạn. Mẫu này bao gồm các phiên thanh toán, xử lý webhook, cổng khách hàng và các thành phần UI hiện đại để giúp bạn bắt đầu chấp nhận thanh toán nhanh chóng.

<Info>
  Boilerplate này sử dụng Astro 5 với TypeScript, Tailwind CSS 4, và adapter `@dodopayments/astro`.
</Info>

### Tính năng

* **Quick Setup** - Bắt đầu trong vòng chưa đến 5 phút
* **Payment Integration** - Luồng thanh toán được cấu hình sẵn sử dụng `@dodopayments/astro`
* **Modern UI** - Trang giá sạch, chủ đề tối với Tailwind CSS
* **Webhook Handler** - Điểm cuối webhook sẵn sàng cho các sự kiện thanh toán
* **Customer Portal** - Quản lý đăng ký chỉ với một cú nhấp
* **TypeScript** - Được gõ kiểu đầy đủ với các kiểu tối thiểu và tập trung
* **Pre-filled Checkout** - Minh họa việc truyền dữ liệu khách hàng để cải thiện trải nghiệm người dùng

## Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn đã có:

* **Phiên bản Node.js LTS** (cần thiết cho Astro 5)
* **Tài khoản Dodo Payments** (để truy cập API và Webhook Keys từ bảng điều khiển)

## Bắt đầu nhanh

<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">
    Đăng ký tại [Dodo Payments](https://dodopayments.com/) và lấy thông tin xác thực từ bảng điều khiển:

    * **API Key:** [Bảng điều khiển → Nhà phát triển → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Bảng điều khiển → Nhà phát triển → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Hãy đảm bảo bạn đang ở **Chế độ kiểm thử** khi phát triển!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Tạo một tệp `.env` ở thư mục gốc:

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

    Cập nhật các giá trị với thông tin xác thực Dodo Payments của bạn:

    ```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>
      Đừng bao giờ commit tệp `.env` của bạn vào hệ thống kiểm soát phiên bản. Nó đã được bao gồm trong `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Cập nhật `src/lib/products.ts` với các ID sản phẩm thực tế từ 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
    ```

    Mở [http://localhost:4321](http://localhost:4321) để xem trang giá của bạn!
  </Step>
</Steps>

## Cấu trúc dự án

```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
```

## Tùy chỉnh

### Cập nhật thông tin sản phẩm

Chỉnh sửa `src/lib/products.ts` để thay đổi:

* ID sản phẩm (từ bảng điều khiển Dodo của bạn)
* Giá cả
* Tính năng
* Mô tả

### Điền trước dữ liệu khách hàng

Trong `src/components/ProductCard.astro`, hãy thay các giá trị được mã hóa cứng bằng dữ liệu người dùng thực tế của bạn:

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

### Cập nhật cổng khách hàng

Trong `src/components/Header.astro`, hãy thay ID khách hàng được mã hóa cứng bằng ID khách hàng thực tế từ hệ thống xác thực hoặc cơ sở dữ liệu của bạn:

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

Bạn có thể hoàn thành một giao dịch thử nghiệm để lấy ID khách hàng cho việc thử nghiệm.

## Sự kiện Webhook

Boilerplate minh họa cách xử lý sự kiện webhook trong `src/pages/api/webhook.ts`:

* `onSubscriptionActive` - Được kích hoạt khi một đăng ký trở nên hoạt động
* `onSubscriptionCancelled` - Được kích hoạt khi một đăng ký bị hủy bỏ

Thêm logic kinh doanh của bạn bên trong các trình xử lý này:

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

Thêm nhiều sự kiện webhook nếu cần.

Đối với phát triển cục bộ, bạn có thể sử dụng các công cụ như [ngrok](https://ngrok.com/) để tạo một đường hầm bảo mật đến máy chủ cục bộ của bạn và sử dụng nó làm URL webhook của bạn.

## Triển khai

Mẫu này sử dụng đầu ra tĩnh với việc kết xuất theo yêu cầu cho các tuyến API. Bạn sẽ cần cài đặt một adapter cho nền tảng triển khai của bạn:

| Nền tảng   | Hướng dẫn                                                                          |
| ---------- | ---------------------------------------------------------------------------------- |
| Vercel     | [Triển khai lên Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Triển khai lên Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Triển khai lên Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

Xem [hướng dẫn triển khai của Astro](https://docs.astro.build/en/guides/deploy/) cho tất cả các nền tảng.

### Cập nhật URL Webhook

Sau khi triển khai, hãy cập nhật URL webhook của bạn trong [Bảng điều khiển Dodo Payments](https://app.dodopayments.com/developer/webhooks):

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

Ngoài ra, hãy nhớ cập nhật biến môi trường `DODO_PAYMENTS_WEBHOOK_KEY` trong môi trường sản xuất của bạn để khớp với khóa ký webhook cho miền đã triển khai.

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Xóa `node_modules` và cài lại các phụ thuộc:

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

  <Accordion title="Checkout redirect fails">
    **Nguyên nhân phổ biến:**

    * ID sản phẩm không hợp lệ - kiểm tra xem nó tồn tại trong bảng điều khiển Dodo của bạn
    * Khóa API hoặc cài đặt môi trường sai trong `.env`
    * Kiểm tra bảng điều khiển trình duyệt và terminal để tìm lỗi
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Để thử nghiệm cục bộ, sử dụng [ngrok](https://ngrok.com) để mở server của bạn ra bên ngoài:

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

    Cập nhật URL webhook trong [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) thành URL ngrok. Hãy nhớ cập nhật tệp .env của bạn với khóa xác minh webhook chính xác.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Thay `CUSTOMER_ID` được mã hóa cứng trong `src/components/Header.astro` bằng ID khách hàng thực tế từ bảng điều khiển Dodo của bạn.

    Hoặc tích hợp hệ thống xác thực và cơ sở dữ liệu của bạn để lấy ID khách hàng một cách động.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    Boilerplate này sử dụng đầu ra tĩnh với các route API theo yêu cầu. Bạn cần cài đặt một adapter để triển khai:

    Xem [các hướng dẫn triển khai của Astro](https://docs.astro.build/en/guides/deploy/) để biết chi tiết.
  </Accordion>
</AccordionGroup>

## Tìm hiểu thêm

* [Tài liệu về Dodo Payments](https://docs.dodopayments.com/)
* [Tài liệu về Phiên Thanh Toán](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Tài liệu về Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## Hỗ trợ

Cần giúp đỡ với mẫu này?

* Tham gia [cộng đồng Discord của chúng tôi](https://discord.gg/bYqAp4ayYh) để đặt câu hỏi và thảo luận
* Kiểm tra [kho GitHub](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) để biết các vấn đề và cập nhật
* Liên hệ với [đội ngũ hỗ trợ của chúng tôi](mailto:support@dodopayments.com) để được trợ giúp