> ## 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.
# Plantilla Mínima de Astro
> Comienza rápidamente con nuestra plantilla mínima de Astro para integrar Dodo Payments en tu aplicación Astro
## Descripción General
La plantilla mínima de Astro proporciona un punto de partida listo para usar para integrar Dodo Payments con tu aplicación Astro. Esta plantilla incluye sesiones de pago, manejo de webhooks, portal de clientes y componentes de UI modernos para ayudarte a comenzar a aceptar pagos rápidamente.
Esta plantilla utiliza Astro 5 con TypeScript, Tailwind CSS 4 y el adaptador `@dodopayments/astro`.
### Características
* **Quick Setup** - Comienza en menos de 5 minutos
* **Payment Integration** - Flujo de pago preconfigurado usando `@dodopayments/astro`
* **Modern UI** - Página de precios limpia y con tema oscuro creada con Tailwind CSS
* **Webhook Handler** - Endpoint de webhook listo para eventos de pago
* **Customer Portal** - Gestión de suscripciones con un clic
* **TypeScript** - Totalmente tipado con tipos mínimos y enfocados
* **Pre-filled Checkout** - Demuestra cómo pasar datos del cliente para mejorar la experiencia
## Requisitos Previos
Antes de comenzar, asegúrate de tener:
* **Versión LTS de Node.js** (requerido para Astro 5)
* **Cuenta de Dodo Payments** (para acceder a las claves de API y Webhook desde el panel de control)
## Inicio Rápido
```bash theme={null}
git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
```
```bash theme={null}
npm install
```
Regístrate en [Dodo Payments](https://dodopayments.com/) y obtén tus credenciales desde el panel de control:
* **Clave de API:** [Panel → Desarrollador → Claves de API](https://app.dodopayments.com/developer/api-keys)
* **Clave de Webhook:** [Panel → Desarrollador → Webhooks](https://app.dodopayments.com/developer/webhooks)
¡Asegúrate de estar en **Modo de Prueba** mientras desarrollas!
Crea un archivo `.env` en el directorio raíz:
```bash theme={null}
cp .env.example .env
```
Actualiza los valores con tus credenciales de Dodo Payments:
```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
```
Nunca subas tu archivo `.env` al control de versiones. Ya está incluido en `.gitignore`.
Actualiza `src/lib/products.ts` con tus IDs de producto reales de 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
];
```
```bash theme={null}
npm run dev
```
Abre [http://localhost:4321](http://localhost:4321) para ver tu página de precios!
## Estructura del Proyecto
```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
```
## Personalización
### Actualiza la Información del Producto
Edita `src/lib/products.ts` para modificar:
* IDs de productos (de tu panel de Dodo)
* Precios
* Características
* Descripciones
### Pre-llenar Datos del Cliente
En `src/components/ProductCard.astro`, reemplaza los valores codificados con tus datos reales de usuario:
```typescript theme={null}
customer: {
name: "John Doe",
email: "john@example.com",
},
```
### Actualiza el Portal de Clientes
En `src/components/Header.astro`, reemplaza el ID de cliente codificado con el ID real de tu sistema de autenticación o base de datos:
```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```
Puedes completar una compra de prueba para obtener el ID de cliente para pruebas.
## Eventos de Webhook
La plantilla demuestra cómo manejar eventos de webhook en `src/pages/api/webhook.ts`:
* `onSubscriptionActive` - Se activa cuando una suscripción se vuelve activa
* `onSubscriptionCancelled` - Se activa cuando una suscripción se cancela
* `onSubscriptionActive` - Activado cuando una suscripción se vuelve activa
* `onSubscriptionCancelled` - Activado cuando una suscripción es cancelada
Agrega tu lógica de negocio dentro de estos manejadores:
```typescript theme={null}
onSubscriptionActive: async (payload) => {
// Grant access to your product
// Update user database
// Send welcome email
},
```
Agrega más eventos de webhook según sea necesario.
Para el desarrollo local, puedes usar herramientas como [ngrok](https://ngrok.com/) para crear un túnel seguro a tu servidor local y usarlo como tu URL de webhook.
## Despliegue
Esta plantilla utiliza salida estática con renderizado bajo demanda para rutas de API. Necesitarás instalar un adaptador para tu plataforma de despliegue:
| Plataforma | Guía |
| ---------- | -------------------------------------------------------------------------------- |
| Vercel | [Desplegar en Vercel](https://docs.astro.build/en/guides/deploy/vercel/) |
| Netlify | [Desplegar en Netlify](https://docs.astro.build/en/guides/deploy/netlify/) |
| Cloudflare | [Desplegar en Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |
Consulta las [guías de despliegue de Astro](https://docs.astro.build/en/guides/deploy/) para todas las plataformas.
### Actualiza la URL de Webhook
Después de desplegar, actualiza tu URL de webhook en el [Panel de Dodo Payments](https://app.dodopayments.com/developer/webhooks):
```text theme={null}
https://your-domain.com/api/webhook
```
También recuerda actualizar la variable de entorno `DODO_PAYMENTS_WEBHOOK_KEY` en tu entorno de producción para que coincida con la clave de firma de webhook de tu dominio desplegado.
## Solución de Problemas
Elimina `node_modules` y vuelve a instalar las dependencias:
```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```
**Causas comunes:**
* ID de producto inválido: verifica que exista en tu panel de Dodo
* Clave API o configuración de entorno incorrecta en `.env`
* Revisa la consola del navegador y la terminal en busca de errores
Para pruebas locales, usa [ngrok](https://ngrok.com) para exponer tu servidor:
```bash theme={null}
ngrok http 4321
```
Actualiza la URL del webhook en tu [panel de Dodo](https://app.dodopayments.com/developer/webhooks) con la URL de ngrok. Recuerda actualizar tu archivo .env con la clave de verificación del webhook correcta.
Reemplaza el `CUSTOMER_ID` codificado en `src/components/Header.astro` con un ID de cliente real de tu panel de Dodo.
O integra tu sistema de autenticación y base de datos para obtener dinámicamente el ID del cliente.
Esta plantilla usa salida estática con rutas API bajo demanda. Necesitas instalar un adaptador para el despliegue:
Consulta [las guías de despliegue de Astro](https://docs.astro.build/en/guides/deploy/) para más detalles.
## Aprende Más
* [Documentación de Dodo Payments](https://docs.dodopayments.com/)
* [Documentación de Sesiones de Pago](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentación de Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)
## Soporte
¿Necesitas ayuda con la plantilla?
* Únete a nuestra [comunidad de Discord](https://discord.gg/bYqAp4ayYh) para preguntas y discusiones
* Revisa el [repositorio de GitHub](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) para problemas y actualizaciones
* Contacta a nuestro [equipo de soporte](mailto:support@dodopayments.com) para asistencia