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

# Go Boilerplate

> Inizia rapidamente con il nostro boilerplate Go minimale per integrare Dodo Payments nelle tue applicazioni backend Go

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/go-boilerplate">
  Boilerplate minimale Go + Dodo Payments
</Card>

## Panoramica

Il boilerplate Go fornisce un punto di partenza pronto per la produzione per integrare Dodo Payments con il tuo backend Go. Questo template include la gestione delle sessioni di checkout, la verifica dei webhook, l'integrazione del portale clienti e segue le migliori pratiche di Go per aiutarti ad accettare pagamenti rapidamente.

<Info>
  Questo boilerplate utilizza Go 1.21+ con pattern di clean architecture (`cmd`, `internal`, `templates`), template HTML e l'SDK `dodopayments-go` per un'integrazione API senza soluzione di continuità.
</Info>

### Caratteristiche

* **Configurazione rapida** - Inizia in meno di 5 minuti
* **Integrazione dei pagamenti** - Flusso di checkout preconfigurato usando l'SDK `dodopayments-go`
* **Interfaccia moderna** - Pagina dei prezzi pulita a tema scuro con template HTML
* **Gestione webhook** - Verifica e processa in modo sicuro gli eventi di pagamento
* **Portale clienti** - Gestione self-service degli abbonamenti
* **Best practice Go** - Architettura pulita con `cmd`, `internal` e `templates`
* **Checkout precompilato** - Dimostra il passaggio dei dati cliente per migliorare l'esperienza utente

## Requisiti

Prima di iniziare, assicurati di avere:

* **Go 1.21+**
* **Account Dodo Payments** (per accedere alle chiavi API e Webhook dal dashboard)

## Avvio Rapido

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

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

    O manualmente:

    ```bash theme={null}
    go mod download
    ```
  </Step>

  <Step title="Get API Credentials">
    Registrati su [Dodo Payments](https://dodopayments.com/) e ottieni le tue credenziali dalla dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Assicurati di essere in **Modalità Test** durante lo sviluppo!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Crea un file `.env` nella directory principale:

    ```bash theme={null}
    cp .env.example .env
    ```

    Aggiorna i valori con le tue credenziali Dodo Payments:

    ```bash .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:8000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Non inserire mai il file `.env` nel controllo versione. È già incluso in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Aggiorna `internal/lib/products.go` con i tuoi ID prodotto effettivi da Dodo Payments:

    ```go theme={null}
    var Products = []Product{
        {
            ProductID:   "pdt_001", // Replace with your product ID
            Name:        "Basic Plan",
            Description: "Get access to basic features and support",
            Price:       9999, // in cents
            Features: []string{
                "Access to basic features",
                "Email support",
                "1 Team member",
                "Basic analytics",
            },
        },
        // ... add more products
    }
    ```
  </Step>

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

    O manualmente:

    ```bash theme={null}
    go run cmd/server/main.go
    ```

    Apri [http://localhost:8000](http://localhost:8000) per vedere la tua pagina di pricing!

    <Check>
      Dovresti vedere una pagina dei prezzi a tema scuro con i tuoi prodotti pronta all'acquisto.
    </Check>
  </Step>
</Steps>

## Struttura del Progetto

```text theme={null}
go-boilerplate/
├── cmd/
│   └── server/             # Application entry point
├── internal/
│   ├── api/                # API handlers (Checkout, Portal, Webhook)
│   ├── core/               # Configuration and system core
│   └── lib/                # Shared logic (Products, Customer utils)
├── templates/              # HTML templates
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md
```

## Endpoint API

Il boilerplate include i seguenti endpoint preconfigurati:

| Endpoint               | Metodo | Descrizione                               |
| ---------------------- | ------ | ----------------------------------------- |
| `/`                    | GET    | Pagina dei prezzi con elenco dei prodotti |
| `/api/checkout`        | POST   | Crea una nuova sessione di checkout       |
| `/api/webhook`         | POST   | Gestisci i webhook di Dodo Payments       |
| `/api/customer-portal` | POST   | Genera l'URL del portale clienti          |

## Personalizzazione

### Aggiorna le Informazioni sul Prodotto

Modifica `internal/lib/products.go` per variare:

* ID dei prodotti (dal tuo dashboard Dodo)
* Prezzi
* Funzionalità
* Descrizioni

```go theme={null}
var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}
```

### Pre-compila i Dati del Cliente

In `templates/index.html`, sostituisci i dati cliente hardcodati con i dati reali dei tuoi utenti:

```javascript theme={null}
const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};
```

In un'app di produzione, inietteresti dinamicamente questi valori dal tuo sistema di autenticazione.

## Eventi Webhook

Il boilerplate dimostra la gestione degli eventi webhook in `internal/api/webhook.go`. Gli eventi supportati includono:

| Evento                | Descrizione                                    |
| --------------------- | ---------------------------------------------- |
| `subscription.active` | Attivato quando un abbonamento diventa attivo  |
| `payment.succeeded`   | Attivato quando un pagamento ha esito positivo |

Aggiungi la tua logica aziendale all'interno del gestore webhook per:

* Aggiornare i permessi utente nel tuo database
* Inviare email di conferma
* Fornire accesso a prodotti digitali
* Monitorare analisi e metriche

## Testare i Webhook Localmente

Per lo sviluppo locale, utilizza strumenti come [ngrok](https://ngrok.com/) per esporre il tuo server locale:

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

Aggiorna l'URL del webhook nel tuo [Dashboard Dodo Payments](https://app.dodopayments.com/developer/webhooks):

```
https://your-ngrok-url.ngrok.io/api/webhook
```

## Distribuzione

### Compila per la Produzione

```bash theme={null}
make build
```

O manualmente:

```bash theme={null}
go build -o bin/server cmd/server/main.go
./bin/server
```

### Distribuisci su Vercel

\[

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

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate))

### Docker

Crea un `Dockerfile`:

```dockerfile theme={null}
FROM golang:1.21-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]
```

Compila ed esegui:

```bash theme={null}
docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo
```

### Considerazioni per la Produzione

<Warning>
  Prima di distribuire in produzione:

  * Passa `DODO_PAYMENTS_ENVIRONMENT` a `live_mode`
  * Usa le chiavi API di produzione dalla dashboard
  * Aggiorna l'URL del webhook al tuo dominio di produzione
  * Abilita HTTPS per tutti gli endpoint
</Warning>

## Risoluzione dei Problemi

<AccordionGroup>
  <Accordion title="Build errors or missing dependencies">
    Assicurati che i moduli Go siano correttamente scaricati:

    ```bash theme={null}
    go mod tidy
    go mod download
    ```
  </Accordion>

  <Accordion title="Checkout session creation fails">
    **Cause comuni:**

    * ID prodotto non valido - verifica che esista nella tua dashboard Dodo
    * Chiave API o impostazione ambiente errate in `.env`
    * Controlla i log del server per messaggi di errore dettagliati
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Per i test locali, usa [ngrok](https://ngrok.com) per esporre il tuo server:

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

    Aggiorna l'URL del webhook nella tua [dashboard Dodo](https://app.dodopayments.com/developer/webhooks) con l'URL di ngrok. Assicurati di aggiornare il file `.env` con la chiave di verifica del webhook corretta.
  </Accordion>

  <Accordion title="Templates not loading">
    Assicurati di eseguire il server dalla directory principale del progetto, oppure che il percorso dei template sia configurato correttamente nel tuo codice.
  </Accordion>
</AccordionGroup>

## Scopri di più

<CardGroup cols={2}>
  <Card title="Go SDK" icon="golang" href="/developer-resources/sdks/go">
    Documentazione completa SDK Go
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Scopri tutti gli eventi webhook e le best practice
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Approfondimento sulla configurazione della sessione di checkout
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Documentazione completa dell'API Dodo Payments
  </Card>
</CardGroup>

## Supporto

Hai bisogno di aiuto con il boilerplate?

* Unisciti alla nostra [comunità Discord](https://discord.gg/bYqAp4ayYh) per domande e discussioni
* Controlla il [repository GitHub](https://github.com/dodopayments/go-boilerplate) per problemi e aggiornamenti
* Contatta il nostro [team di supporto](mailto:support@dodopayments.com) per assistenza