> ## 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 Next.js
> Clona la plantilla base minimalista de Next.js para obtener una página de precios, sesiones de checkout, un controlador de webhooks y un enlace al Customer Portal conectados a Dodo Payments.
## Descripción General
La plantilla base minimalista de Next.js es una aplicación inicial con Dodo Payments ya conectado. Añade tus claves de API y los ID de tus productos para obtener una página de precios que abre el checkout, un endpoint de webhook para los eventos de pago y un enlace al Customer Portal.
Esta plantilla base utiliza el App Router de Next.js 16 con TypeScript, Tailwind CSS 4 y el adaptador `@dodopayments/nextjs`. Para añadir los mismos route handlers a una aplicación existente, consulta [Next.js Adaptor](/developer-resources/nextjs-adaptor).
### Características
La plantilla base incluye:
* **Configuración rápida**: pasa de clonar el repositorio a tener una página de precios en funcionamiento en unos cinco minutos.
* **Checkout**: un flujo de checkout preconfigurado basado en `@dodopayments/nextjs`.
* **Página de precios**: una página de precios con tema oscuro y estilos de Tailwind CSS.
* **Webhook Handler**: un endpoint que verifica la firma de cada webhook y ejecuta tu código para el evento.
* **Customer Portal**: un enlace en el encabezado que abre el Customer Portal, donde los clientes gestionan sus suscripciones.
* **TypeScript**: definiciones y handlers de productos tipados.
* **Checkout precompletado**: envía el nombre y el correo electrónico del cliente al checkout para que no tenga que volver a escribirlos.
## Requisitos previos
Antes de comenzar, necesitas:
* **Node.js 20.9 o posterior**, que es obligatorio para Next.js 16.
* **Una cuenta de Dodo Payments**, para crear una clave de API y un secreto de firma de webhook en el dashboard.
## Inicio rápido
```bash theme={null}
git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate
```
```bash theme={null}
npm install
```
Regístrate en [Dodo Payments](https://dodopayments.com/) y obtén tus credenciales en el dashboard:
* **API Key:** crea una clave en [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys).
* **Webhook Key:** añade un endpoint en [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks) y copia su secreto de firma. La URL del endpoint debe ser pública y utilizar HTTPS. Para recibir eventos en tu equipo, consulta [Webhook Events](#webhook-events).
Crea ambos mientras el interruptor de **Live Mode** de la barra lateral esté desactivado. Una clave del modo de prueba solo funciona con `DODO_PAYMENTS_ENVIRONMENT=test_mode`, y los pagos del modo de prueba no mueven dinero real.
Copia el archivo de ejemplo para crear un archivo `.env` en el directorio raíz:
```bash theme={null}
cp .env.example .env
```
Configura 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:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode
```
Los route handlers leen estas variables:
* `DODO_PAYMENTS_API_KEY` autentica los handlers de checkout y Customer Portal.
* `DODO_PAYMENTS_WEBHOOK_KEY` verifica las firmas de los webhooks.
* `DODO_PAYMENTS_RETURN_URL` indica dónde envía checkout al cliente después del pago.
* `DODO_PAYMENTS_ENVIRONMENT` es `test_mode` o `live_mode`.
No confirmes tu archivo `.env` en el control de versiones. El archivo `.gitignore` del repositorio ya lo excluye.
Sustituye los productos de ejemplo en `src/lib/products.ts` por los tuyos. Configura cada `product_id` con el ID de un producto incluido en **Products** en tu dashboard:
```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
];
```
La página de precios muestra `name`, `description`, `price` y `features` de este archivo. Checkout cobra el precio configurado en el producto de Dodo Payments, así que mantén `price` sincronizado con él.
```bash theme={null}
npm run dev
```
Abre [http://localhost:3000](http://localhost:3000) para ver tu página de precios.
## Estructura del proyecto
Los route handlers de checkout, Customer Portal y webhook se encuentran en `src/app/api/`:
```text theme={null}
src/
├── app/
│ ├── api/
│ │ ├── checkout/ # Checkout session handler
│ │ ├── customer-portal/ # Customer portal redirect
│ │ └── webhook/ # Webhook event handler
│ ├── components/
│ │ ├── Footer.tsx # Reusable footer
│ │ ├── Header.tsx # Navigation header
│ │ └── ProductCard.tsx # Product pricing card
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Pricing page (home)
└── lib/
└── products.ts # Product definitions
```
## Personalización
### Actualizar la información del producto
Edita `src/lib/products.ts` para cambiar:
* Los ID de los productos, desde **Products** en tu dashboard de Dodo Payments
* Los precios
* Las funciones
* Las descripciones
### Precompletar los datos del cliente
`src/app/components/ProductCard.tsx` envía un nombre y un correo electrónico codificados directamente en cada solicitud de checkout. Sustitúyelos por los datos del usuario que ha iniciado sesión:
```typescript theme={null}
customer: {
name: "John Doe",
email: "john@example.com",
},
```
### Actualizar Customer Portal
El enlace de **Customer Portal** en `src/app/components/Header.tsx` abre `/api/customer-portal` con un ID de cliente codificado directamente. Sustitúyelo por el ID de cliente de Dodo Payments del usuario que ha iniciado sesión:
```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```
Para obtener un ID de cliente para realizar pruebas, completa una compra de prueba y copia el ID del cliente desde **Customers** en el dashboard. En producción, obtén el ID desde tu backend.
## Eventos de webhook
El handler en `src/app/api/webhook/route.ts` verifica cada solicitud con `DODO_PAYMENTS_WEBHOOK_KEY` y, después, gestiona dos eventos:
* `onSubscriptionActive` se ejecuta cuando una suscripción pasa a estar activa (`subscription.active`).
* `onPaymentSucceeded` se ejecuta cuando un pago se realiza correctamente (`payment.succeeded`).
Añade tu lógica de negocio dentro de estos handlers:
```typescript theme={null}
onSubscriptionActive: async (payload) => {
// Grant access to your product
// Update user database
// Send welcome email
},
```
Para gestionar más eventos, añade sus handlers, como `onSubscriptionCancelled`. [Next.js Adaptor](/developer-resources/nextjs-adaptor#supported-webhook-event-handlers) contiene la lista de todos los handlers compatibles.
Dodo Payments no puede acceder a `localhost`. Para el desarrollo local, utiliza un túnel como [ngrok](https://ngrok.com/) para exponer tu servidor local y usa la URL del túnel como endpoint de webhook.
## Implementación
### Compilar para producción
```bash theme={null}
npm run build
npm start
```
### Implementar en Vercel
\[
]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate))
Añade las cuatro variables de entorno en el dashboard de Vercel y configura `DODO_PAYMENTS_RETURN_URL` con tu URL de producción.
### Actualizar la URL del webhook
Después de la implementación, añade la URL de tu webhook de producción en [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks), sustituyendo `example.com` por tu dominio:
```text theme={null}
https://example.com/api/webhook
```
Cada endpoint tiene su propio secreto de firma. Copia el secreto del nuevo endpoint en `DODO_PAYMENTS_WEBHOOK_KEY` en tu entorno de producción.
## Solución de problemas
Elimina `node_modules` y `package-lock.json` y, después, reinstala las dependencias:
```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```
Comprueba estas causas habituales:
* El ID del producto no existe en tu dashboard de Dodo Payments.
* La API key o `DODO_PAYMENTS_ENVIRONMENT` en `.env` es incorrecta. Una clave del modo de prueba solo funciona con `test_mode`.
Busca el error en la consola del navegador y en el terminal que ejecuta `npm run dev`.
Para realizar pruebas locales, utiliza [ngrok](https://ngrok.com) para exponer tu servidor:
```bash theme={null}
ngrok http 3000
```
En tu [Dodo dashboard](https://app.dodopayments.com/developer/webhooks), añade un endpoint con la URL HTTPS de ngrok seguida de `/api/webhook`. Copia el secreto de firma de ese endpoint en `DODO_PAYMENTS_WEBHOOK_KEY` dentro de tu archivo `.env`.
Sustituye el `CUSTOMER_ID` codificado directamente en `src/app/components/Header.tsx` por el ID de un cliente de tu dashboard de Dodo Payments.
En producción, obtén el ID del cliente desde tu sistema de autenticación y tu base de datos.
## Más información
* [Documentación de Dodo Payments](https://docs.dodopayments.com/)
* [Documentación de Checkout Sessions](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentación de Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)
* [Next.js Adaptor](/developer-resources/nextjs-adaptor): opciones para los handlers `Checkout`, `CustomerPortal` y `Webhooks`
## Soporte
Para obtener ayuda con la plantilla base:
* Haz preguntas en la [comunidad de Discord](https://discord.gg/bYqAp4ayYh).
* Informa de problemas y sigue las novedades en el [repositorio de GitHub](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate).
* Envía un correo electrónico al [equipo de soporte](mailto:support@dodopayments.com).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.