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

> Comece rapidamente com nosso boilerplate mínimo em Go para integrar os pagamentos Dodo em suas aplicações backend em Go

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

## Visão Geral

O boilerplate em Go fornece um ponto de partida pronto para produção para integrar os pagamentos Dodo com seu backend em Go. Este template inclui manipulação de sessão de checkout, verificação de webhook, integração com o portal do cliente e segue as melhores práticas de Go para ajudá-lo a começar a aceitar pagamentos rapidamente.

<Info>
  Este boilerplate usa Go 1.21+ com padrões de arquitetura limpa (`cmd`, `internal`, `templates`), templates HTML e o SDK `dodopayments-go` para integração perfeita com APIs.
</Info>

### Recursos

* **Configuração rápida** - Comece em menos de 5 minutos
* **Integração de pagamentos** - Fluxo de checkout pré-configurado usando o SDK `dodopayments-go`
* **Interface moderna** - Página de preços limpa com tema escuro usando templates HTML
* **Tratamento de webhooks** - Verifique e processe eventos de pagamento com segurança
* **Portal do cliente** - Gerenciamento de assinaturas em modo self-service
* **Boas práticas em Go** - Arquitetura limpa com `cmd`, `internal` e `templates`
* **Checkout com campos preenchidos** - Demonstra como passar dados do cliente para melhorar a experiência do usuário

## Pré-requisitos

Antes de começar, certifique-se de que você tem:

* **Go 1.21+**
* **Conta Dodo Payments** (para acessar as chaves da API e do Webhook no painel)

## Início Rápido

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

    Ou manualmente:

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

  <Step title="Get API Credentials">
    Cadastre-se em [Dodo Payments](https://dodopayments.com/) e obtenha suas credenciais no painel:

    * **Chave da API:** [Painel → Desenvolvedor → Chaves da API](https://app.dodopayments.com/developer/api-keys)
    * **Chave do Webhook:** [Painel → Desenvolvedor → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Certifique-se de estar em **Modo de Teste** enquanto desenvolve!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Crie um arquivo `.env` no diretório raiz:

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

    Atualize os valores com suas credenciais do 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>
      Nunca faça commit do seu arquivo `.env` no controle de versão. Ele já está incluído em `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Atualize `internal/lib/products.go` com seus IDs de produto reais do 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
    ```

    Ou manualmente:

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

    Abra [http://localhost:8000](http://localhost:8000) para ver sua página de preços!

    <Check>
      Você deverá ver uma página de preços com tema escuro e seus produtos prontos para compra.
    </Check>
  </Step>
</Steps>

## Estrutura do Projeto

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

## Endpoints da API

O boilerplate inclui os seguintes endpoints pré-configurados:

| Endpoint               | Método | Descrição                                 |
| ---------------------- | ------ | ----------------------------------------- |
| `/`                    | GET    | Página de preços com listagem de produtos |
| `/api/checkout`        | POST   | Cria uma nova sessão de checkout          |
| `/api/webhook`         | POST   | Trata webhooks do Dodo Payments           |
| `/api/customer-portal` | POST   | Gera URL do portal do cliente             |

## Personalização

### Atualizar Informações do Produto

Edite `internal/lib/products.go` para modificar:

* IDs de produto (do seu painel Dodo)
* Preços
* Recursos
* Descrições

```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",
        },
    },
}
```

### Pré-preencher Dados do Cliente

No `templates/index.html`, substitua os dados do cliente codificados com seus dados reais de usuário:

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

Em um aplicativo de produção, você injetaria dinamicamente esses valores do seu sistema de autenticação.

## Eventos de Webhook

O boilerplate demonstra como lidar com eventos de webhook em `internal/api/webhook.go`. Os eventos suportados incluem:

| Evento                | Descrição                                      |
| --------------------- | ---------------------------------------------- |
| `subscription.active` | Disparado quando uma assinatura se torna ativa |
| `payment.succeeded`   | Disparado quando um pagamento é bem-sucedido   |

Adicione sua lógica de negócios dentro do manipulador de webhook para:

* Atualizar permissões de usuário em seu banco de dados
* Enviar e-mails de confirmação
* Provisionar acesso a produtos digitais
* Rastrear análises e métricas

## Testando Webhooks Localmente

Para desenvolvimento local, use ferramentas como [ngrok](https://ngrok.com/) para expor seu servidor local:

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

Atualize a URL do webhook em seu [Painel do Dodo Payments](https://app.dodopayments.com/developer/webhooks):

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

## Implantação

### Compilar para Produção

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

Ou manualmente:

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

### Implantar no Vercel

\[

![Implantar com 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

Crie um `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"]
```

Compile e execute:

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

### Considerações para Produção

<Warning>
  Antes de implantar em produção:

  * Troque `DODO_PAYMENTS_ENVIRONMENT` por `live_mode`
  * Use chaves de API de produção do painel
  * Atualize a URL do webhook para seu domínio de produção
  * Habilite HTTPS em todos os endpoints
</Warning>

## Resolução de Problemas

<AccordionGroup>
  <Accordion title="Build errors or missing dependencies">
    Garanta que os módulos Go sejam baixados corretamente:

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

  <Accordion title="Checkout session creation fails">
    **Causas comuns:**

    * ID de produto inválido - verifique se ele existe no seu painel Dodo
    * Chave de API ou ambiente incorreto em `.env`
    * Confira os logs do servidor para mensagens detalhadas de erro
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Para testes locais, use [ngrok](https://ngrok.com) para expor seu servidor:

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

    Atualize a URL do webhook no seu [painel Dodo](https://app.dodopayments.com/developer/webhooks) para a URL do ngrok. Certifique-se de atualizar seu arquivo `.env` com a chave de verificação correta do webhook.
  </Accordion>

  <Accordion title="Templates not loading">
    Certifique-se de executar o servidor a partir do diretório raiz do projeto ou que o caminho das templates esteja corretamente configurado no seu código.
  </Accordion>
</AccordionGroup>

## Saiba Mais

<CardGroup cols={2}>
  <Card title="Go SDK" icon="golang" href="/developer-resources/sdks/go">
    Documentação completa do SDK Go
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Saiba mais sobre todos os eventos de webhook e melhores práticas
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Mergulhe na configuração de sessões de checkout
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Documentação completa da API Dodo Payments
  </Card>
</CardGroup>

## Suporte

Precisa de ajuda com o boilerplate?

* Junte-se à nossa [comunidade no Discord](https://discord.gg/bYqAp4ayYh) para perguntas e discussões
* Verifique o [repositório do GitHub](https://github.com/dodopayments/go-boilerplate) para problemas e atualizações
* Entre em contato com nossa [equipe de suporte](mailto:support@dodopayments.com) para assistência