> ## 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.
# Astro Minimal Boilerplate
> Comece rapidamente com nosso boilerplate mínimo Astro para integrar os Pagamentos Dodo em sua aplicação Astro
## Visão Geral
O boilerplate mínimo Astro fornece um ponto de partida pronto para uso para integrar os Pagamentos Dodo com sua aplicação Astro. Este template inclui sessões de checkout, manipulação de webhook, portal do cliente e componentes de UI modernos para ajudá-lo a começar a aceitar pagamentos rapidamente.
Este boilerplate usa Astro 5 com TypeScript, Tailwind CSS 4 e o adaptador `@dodopayments/astro`.
### Recursos
* **Quick Setup** - Comece em menos de 5 minutos
* **Payment Integration** - Fluxo de checkout pré-configurado usando `@dodopayments/astro`
* **Modern UI** - Página de preços limpa, com tema escuro, usando Tailwind CSS
* **Webhook Handler** - Endpoint pronto para uso para eventos de pagamento
* **Customer Portal** - Gerenciamento de assinaturas com um clique
* **TypeScript** - Totalmente tipado com tipos mínimos e direcionados
* **Pre-filled Checkout** - Demonstra como passar dados do cliente para melhorar a experiência
## Pré-requisitos
Antes de começar, certifique-se de que você tem:
* **Node.js versão LTS** (necessário para Astro 5)
* **Conta Dodo Payments** (para acessar as chaves da API e do Webhook no painel)
## Início Rápido
```bash theme={null}
git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
```
```bash theme={null}
npm install
```
Inscreva-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)
Certifique-se de estar no **Modo de Teste** durante o desenvolvimento!
Crie um arquivo `.env` no diretório raiz:
```bash theme={null}
cp .env.example .env
```
Atualize os valores com suas credenciais do 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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode
```
Nunca faça commit de seu arquivo `.env` no controle de versão. Ele já está incluído em `.gitignore`.
Atualize `src/lib/products.ts` com seus IDs de produto reais da 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
];
```
```bash theme={null}
npm run dev
```
Abra [http://localhost:4321](http://localhost:4321) para ver sua página de preços!
## Estrutura do Projeto
```text theme={null}
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
```
## Personalização
### Atualizar Informações do Produto
Edite `src/lib/products.ts` para alterar:
* IDs de produto (do seu painel Dodo)
* Preços
* Funcionalidades
* Descrições
### Pré-preencher Dados do Cliente
No `src/components/ProductCard.astro`, substitua os valores codificados pelos seus dados reais de usuário:
```typescript theme={null}
customer: {
name: "John Doe",
email: "john@example.com",
},
```
### Atualizar Portal do Cliente
Em `src/components/Header.astro`, substitua o ID de cliente codificado pelo ID real do cliente do seu sistema de autenticação ou banco de dados:
```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```
Você pode completar uma compra de teste para obter o ID do cliente para testes.
## Eventos de Webhook
O boilerplate demonstra o tratamento de eventos de webhook em `src/pages/api/webhook.ts`:
* `onSubscriptionActive` - Disparado quando uma assinatura se torna ativa
* `onSubscriptionCancelled` - Disparado quando uma assinatura é cancelada
Adicione sua lógica de negócios dentro desses manipuladores:
```typescript theme={null}
onSubscriptionActive: async (payload) => {
// Grant access to your product
// Update user database
// Send welcome email
},
```
Adicione mais eventos de webhook conforme necessário.
Para desenvolvimento local, você pode usar ferramentas como [ngrok](https://ngrok.com/) para criar um túnel seguro para seu servidor local e usá-lo como sua URL de webhook.
## Implantação
Este boilerplate usa saída estática com renderização sob demanda para rotas de API. Você precisará instalar um adapter para sua plataforma de implantação:
| Plataforma | Guia |
| ---------- | -------------------------------------------------------------------------------- |
| Vercel | [Implantar no Vercel](https://docs.astro.build/en/guides/deploy/vercel/) |
| Netlify | [Implantar no Netlify](https://docs.astro.build/en/guides/deploy/netlify/) |
| Cloudflare | [Implantar no Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |
Veja os [guias de implantação do Astro](https://docs.astro.build/en/guides/deploy/) para todas as plataformas.
### Atualizar URL do Webhook
Após a implantação, atualize sua URL de webhook no [Painel Dodo Payments](https://app.dodopayments.com/developer/webhooks):
```text theme={null}
https://your-domain.com/api/webhook
```
Lembre-se também de atualizar a variável de ambiente `DODO_PAYMENTS_WEBHOOK_KEY` em seu ambiente de produção para corresponder à chave de assinatura do webhook para o seu domínio implantado.
## Solução de Problemas
Exclua `node_modules` e reinstale as dependências:
```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```
**Causas comuns:**
* ID do produto inválido - verifique se existe no seu painel Dodo
* Chave de API ou configuração de ambiente incorreta em `.env`
* Verifique o console do navegador e o terminal em busca de erros
Para testes locais, use [ngrok](https://ngrok.com) para expor seu servidor:
```bash theme={null}
ngrok http 4321
```
Atualize a URL do webhook no seu [painel Dodo](https://app.dodopayments.com/developer/webhooks) para a URL do ngrok. Lembre-se de atualizar seu arquivo .env com a chave de verificação do webhook correta.
Substitua o `CUSTOMER_ID` codificado em `src/components/Header.astro` por um ID de cliente real do seu painel Dodo.
Ou integre seu sistema de autenticação e banco de dados para buscar o ID do cliente dinamicamente.
Este boilerplate usa saída estática com rotas de API sob demanda. Você precisa instalar um adaptador para implantação:
Consulte os [guias de implantação do Astro](https://docs.astro.build/en/guides/deploy/) para mais detalhes.
## Saiba Mais
* [Documentação do Dodo Payments](https://docs.dodopayments.com/)
* [Documentação das Sessões de Checkout](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentação dos Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)
## 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/dodo-astro-minimal-boilerplate) para problemas e atualizações
* Entre em contato com nossa [equipe de suporte](mailto:support@dodopayments.com) para assistência