Astro Minimal Boilerplate - Dodo Payments Documentation

Panoramica

Il boilerplate Astro minimale fornisce un punto di partenza pronto all’uso per integrare Dodo Payments con la tua applicazione Astro. Questo template include sessioni di checkout, gestione dei webhook, portale clienti e componenti UI moderni per aiutarti ad accettare pagamenti rapidamente.

Questo boilerplate utilizza Astro 5 con TypeScript, Tailwind CSS 4 e l’adapter @dodopayments/astro.

Caratteristiche

Configurazione rapida - Inizia in meno di 5 minuti
Integrazione pagamenti - Flusso di checkout preconfigurato con @dodopayments/astro
UI moderna - Pagina prezzi pulita e a tema scuro con Tailwind CSS
Gestore webhook - Endpoint webhook pronto all’uso per gli eventi di pagamento
Portale clienti - Gestione abbonamenti con un clic
TypeScript - Tipizzazione completa con tipi minimi e mirati
Checkout precompilato - Mostra come passare i dati del cliente per migliorare l’esperienza utente

Requisiti

Prima di iniziare, assicurati di avere:

Versione LTS di Node.js (richiesta per Astro 5)
Account Dodo Payments (per accedere alle chiavi API e Webhook dal dashboard)

Avvio Rapido

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

Iscriviti a Dodo Payments e ottieni le tue credenziali dalla dashboard:

API Key: Dashboard → Developer → API Keys
Webhook Key: Dashboard → Developer → Webhooks

Assicurati di essere in Modalità Test durante lo sviluppo!

Configure Environment Variables

Crea un file .env nella directory principale:

cp .env.example .env

Aggiorna i valori con le tue credenziali 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

Non inserire mai il tuo file .env nel controllo versione. È già incluso in .gitignore.

Add Your Products

Aggiorna src/lib/products.ts con i tuoi ID prodotto reali da 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

Apri http://localhost:4321 per vedere la tua pagina prezzi!

Struttura del Progetto

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

Personalizzazione

Aggiorna le Informazioni sul Prodotto

Modifica src/lib/products.ts per aggiornare:

ID prodotto (dalla tua dashboard Dodo)
Prezzi
Funzionalità
Descrizioni

Pre-compila i Dati del Cliente

In src/components/ProductCard.astro, sostituisci i valori hardcoded con i dati reali del tuo utente:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Aggiorna il Portale Clienti

In src/components/Header.astro, sostituisci l’ID cliente hardcoded con l’ID cliente reale del tuo sistema di autenticazione o database:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Puoi completare un acquisto di prova per ottenere l’ID cliente per il testing.

Eventi Webhook

Il boilerplate dimostra la gestione degli eventi webhook in src/pages/api/webhook.ts:

onSubscriptionActive - Attivato quando un abbonamento diventa attivo
onSubscriptionCancelled - Attivato quando un abbonamento viene annullato

Aggiungi la tua logica aziendale all’interno di questi gestori:

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

Aggiungi ulteriori eventi webhook se necessario. Per lo sviluppo locale, puoi utilizzare strumenti come ngrok per creare un tunnel sicuro al tuo server locale e usarlo come URL del tuo webhook.

Distribuzione

Questo boilerplate utilizza output statico con rendering on-demand per le rotte API. Dovrai installare un adapter per la tua piattaforma di distribuzione:

Piattaforma	Guida
Vercel	Distribuisci su Vercel
Netlify	Distribuisci su Netlify
Cloudflare	Distribuisci su Cloudflare

Consulta le guide alla distribuzione di Astro per tutte le piattaforme.

Aggiorna l’URL del Webhook

Dopo la distribuzione, aggiorna il tuo URL del webhook nel Dashboard di Dodo Payments:

https://your-domain.com/api/webhook

Ricorda anche di aggiornare la variabile d’ambiente DODO_PAYMENTS_WEBHOOK_KEY nel tuo ambiente di produzione per abbinare la chiave di firma webhook per il dominio distribuito.

Risoluzione dei Problemi

Module not found or build errors

Elimina node_modules e reinstalla le dipendenze:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Cause comuni:

ID prodotto non valido - verifica che esista nella tua dashboard Dodo
Chiave API errata o impostazione ambiente sbagliata in .env
Controlla la console del browser e il terminale per gli errori

Webhooks not receiving events

Per i test locali, usa ngrok per esporre il tuo server:

ngrok http 4321

Aggiorna l’URL del webhook nella tua dashboard Dodo con l’URL ngrok. Ricorda di aggiornare il file .env con la chiave di verifica webhook corretta.

Customer portal link doesn't work

Sostituisci l’hardcoded CUSTOMER_ID in src/components/Header.astro con un ID cliente reale dalla tua dashboard Dodo.Oppure integra il tuo sistema di autenticazione e database per recuperare dinamicamente l’ID cliente.

Build fails with adapter error

Questo boilerplate usa output statico con API routes on-demand. È necessario installare un adapter per la distribuzione:Consulta le guide di distribuzione di Astro per i dettagli.

Scopri di Più

Supporto

Hai bisogno di aiuto con il boilerplate?

Unisciti alla nostra comunità Discord per domande e discussioni
Controlla il repository GitHub per problemi e aggiornamenti
Contatta il nostro team di supporto per assistenza

​Panoramica

​Caratteristiche

​Requisiti

​Avvio Rapido

​Struttura del Progetto

​Personalizzazione

​Aggiorna le Informazioni sul Prodotto

​Pre-compila i Dati del Cliente

​Aggiorna il Portale Clienti

​Eventi Webhook

​Distribuzione

​Aggiorna l’URL del Webhook

​Risoluzione dei Problemi

​Scopri di Più

​Supporto

Panoramica

Caratteristiche

Requisiti

Avvio Rapido

Struttura del Progetto

Personalizzazione

Aggiorna le Informazioni sul Prodotto

Pre-compila i Dati del Cliente

Aggiorna il Portale Clienti

Eventi Webhook

Distribuzione

Aggiorna l’URL del Webhook

Risoluzione dei Problemi

Scopri di Più

Supporto