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

> Comienza rápidamente con nuestra plantilla mínima de Next.js para integrar Dodo Payments en tu aplicación Next.js

## Descripción General

La plantilla mínima de Next.js proporciona un punto de partida listo para usar para integrar Dodo Payments con tu aplicación Next.js. 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.

<Info>
  Este boilerplate utiliza Next.js 16 App Router con TypeScript, Tailwind CSS 4 y el adaptador `@dodopayments/nextjs`.
</Info>

### Características

* **Configuración rápida** - Comienza en menos de 5 minutos
* **Integración de pagos** - Flujo de pago preconfigurado usando `@dodopayments/nextjs`
* **IU moderna** - Página de precios limpia con tema oscuro utilizando Tailwind CSS
* **Manejador de webhooks** - Endpoint listo para eventos de pago
* **Portal del cliente** - Gestión de suscripciones con un clic
* **TypeScript** - Totalmente tipado con tipos mínimos y enfocados
* **Checkout prellenado** - Demuestra el envío de datos del cliente para mejorar la experiencia

## Requisitos Previos

Antes de comenzar, asegúrate de tener:

* **Node.js 20.9+** (requerido para Next.js 16)
* **Cuenta de Dodo Payments** (para acceder a las claves de API y Webhook desde el panel de control)

## Inicio Rápido

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

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

  <Step title="Get API Credentials">
    Regístrate en [Dodo Payments](https://dodopayments.com/) y obtén tus credenciales desde el panel:

    * **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)

    <Tip>
      ¡Asegúrate de estar en **Test Mode** mientras desarrollas!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    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:3000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Nunca subas tu archivo `.env` al control de versiones. Ya está incluido en `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Actualiza `src/lib/products.ts` con tus ID de productos 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
    ];
    ```
  </Step>

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

    ¡Abre [http://localhost:3000](http://localhost:3000) para ver tu página de precios!
  </Step>
</Steps>

## Estructura del Proyecto

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

### Actualiza la Información del Producto

Edita `src/lib/products.ts` para modificar:

* IDs de producto (desde tu panel de Dodo)
* Precios
* Funcionalidades
* Descripciones

### Pre-llenar Datos del Cliente

En `src/app/components/ProductCard.tsx`, 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/app/components/Header.tsx`, reemplaza el ID de cliente codificado:

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

El boilerplate demuestra el manejo de dos eventos webhook en `src/app/api/webhook/route.ts`:

* `onSubscriptionActive` - Se activa cuando una suscripción se vuelve activa
* `onPaymentSucceeded` - Se activa cuando un pago es exitoso

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

### Construir para Producción

```bash theme={null}
npm run build
npm start
```

### Desplegar en Vercel

\[

![Desplegar con Vercel](https://vercel.com/button)

]\([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))

¡No olvides agregar tus variables de entorno en el panel de Vercel!

### 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):

```
https://example.com/api/webhook
```

## Solución de Problemas

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Elimina `node_modules` y reinstala las dependencias:

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

  <Accordion title="Checkout redirect fails">
    **Causas comunes:**

    * ID de producto inválido: verifica que exista en tu panel de Dodo
    * Clave de API incorrecta o configuración de entorno errónea en `.env`
    * Revisa la consola del navegador y el terminal en busca de errores
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Para pruebas locales, usa [ngrok](https://ngrok.com) para exponer tu servidor:

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

    Actualiza la URL del webhook en tu [panel de Dodo](https://app.dodopayments.com/developer/webhooks) a la URL de ngrok. Recuerda actualizar tu archivo .env con la clave correcta de verificación del webhook.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Reemplaza la `CUSTOMER_ID` codificada en `src/app/components/Header.tsx` 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 de cliente.
  </Accordion>
</AccordionGroup>

## 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-nextjs-minimal-boilerplate) para problemas y actualizaciones
* Contacta a nuestro [equipo de soporte](mailto:support@dodopayments.com) para asistencia