Plantilla Mínima de Astro - Dodo Payments Documentation

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

Clone the Repository

git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Regístrate en Dodo Payments y obtén tus credenciales desde el panel de control:

Clave de API: Panel → Desarrollador → Claves de API
Clave de Webhook: Panel → Desarrollador → Webhooks

¡Asegúrate de estar en Modo de Prueba mientras desarrollas!

Configure Environment Variables

Crea un archivo .env en el directorio raíz:

cp .env.example .env

Actualiza los valores con tus credenciales de Dodo Payments:

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.

Add Your Products

Actualiza src/lib/products.ts con tus IDs de producto reales de Dodo Payments:

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
];

Run the Development Server

npm run dev

Abre http://localhost:4321 para ver tu página de precios!

Estructura del Proyecto

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:

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:

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:

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 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
Netlify	Desplegar en Netlify
Cloudflare	Desplegar en Cloudflare

Consulta las guías de despliegue de Astro 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://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

Module not found or build errors

Elimina node_modules y vuelve a instalar las dependencias:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

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

Webhooks not receiving events

Para pruebas locales, usa ngrok para exponer tu servidor:

ngrok http 4321

Actualiza la URL del webhook en tu panel de Dodo con la URL de ngrok. Recuerda actualizar tu archivo .env con la clave de verificación del webhook correcta.

Customer portal link doesn't work

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.

Build fails with adapter error

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 para más detalles.

Aprende Más

Soporte

¿Necesitas ayuda con la plantilla?

Únete a nuestra comunidad de Discord para preguntas y discusiones
Revisa el repositorio de GitHub para problemas y actualizaciones
Contacta a nuestro equipo de soporte para asistencia

​Descripción General

​Características

​Requisitos Previos

​Inicio Rápido

​Estructura del Proyecto

​Personalización

​Actualiza la Información del Producto

​Pre-llenar Datos del Cliente

​Actualiza el Portal de Clientes

​Eventos de Webhook

​Despliegue

​Actualiza la URL de Webhook

​Solución de Problemas

​Aprende Más

​Soporte

Descripción General

Características

Requisitos Previos

Inicio Rápido

Estructura del Proyecto

Personalización

Actualiza la Información del Producto

Pre-llenar Datos del Cliente

Actualiza el Portal de Clientes

Eventos de Webhook

Despliegue

Actualiza la URL de Webhook

Solución de Problemas

Aprende Más

Soporte