Pular para o conteúdo principal

​
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 @dodopayments/astro adapter.

​
Recursos

  • Configuração Rápida - Comece em menos de 5 minutos
  • Integração de Pagamento - Fluxo de checkout pré-configurado usando @dodopayments/astro
  • UI Moderna - Página de preços limpa e com tema escuro usando Tailwind CSS
  • Manipulador de Webhook - Endpoint de webhook pronto para uso para eventos de pagamento
  • Portal do Cliente - Gerenciamento de assinatura com um clique
  • TypeScript - Totalmente tipado com tipos mínimos e focados
  • Checkout Pré-preenchido - Demonstra a passagem de dados do cliente para melhorar a experiência do usuário

​
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

1

Clone o Repositório

git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
2

Instalar Dependências

npm install
3

Obter Credenciais da API

Inscreva-se em Dodo Payments e obtenha suas credenciais no painel:
Certifique-se de que você está em Modo de Teste enquanto desenvolve!
4

Configurar Variáveis de Ambiente

Crie um arquivo .env no diretório raiz:
cp .env.example .env
Atualize os valores com suas credenciais do 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
Nunca comite seu arquivo .env no controle de versão. Ele já está incluído em .gitignore.
5

Adicione Seus Produtos

Atualize src/lib/products.ts com seus IDs de produto reais do 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
];
6

Execute o Servidor de Desenvolvimento

npm run dev
Abra http://localhost:4321 para ver sua página de preços!

​
Estrutura do Projeto

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 modificar:
  • IDs dos produtos (do seu painel Dodo)
  • Preços
  • Recursos
  • Descrições

​
Pré-preencher Dados do Cliente

Em src/components/ProductCard.astro, substitua os valores codificados por dados reais do usuário: 
customer: {
  name: "John Doe",
  email: "[email protected]",
},

​
Atualizar Portal do Cliente

Em src/components/Header.astro, substitua o ID do cliente codificado pelo ID real do cliente do seu sistema de autenticação ou banco de dados: 
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 como lidar com eventos de webhook em src/pages/api/webhook.ts:
  • onSubscriptionActive - Acionado quando uma assinatura se torna ativa
  • onSubscriptionCancelled - Acionado quando uma assinatura é cancelada
Adicione sua lógica de negócios dentro desses manipuladores: 
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 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:
PlataformaGuia
VercelImplantar no Vercel
NetlifyImplantar no Netlify
CloudflareImplantar no Cloudflare
Veja os guias de implantação do Astro para todas as plataformas.

​
Atualizar URL do Webhook

Após a implantação, atualize sua URL de webhook no Painel Dodo Payments: 
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 seu domínio implantado.

​
Solução de Problemas

Delete node_modules e reinstale as dependências:
rm -rf node_modules package-lock.json
npm install
Causas comuns:
  • ID do produto inválido - verifique se ele existe no seu painel Dodo
  • Chave da API errada ou configuração de ambiente em .env
  • Verifique o console do navegador e o terminal em busca de erros
Para testes locais, use ngrok para expor seu servidor:
ngrok http 4321
Atualize a URL do webhook em seu painel Dodo para a URL do ngrok. Lembre-se de atualizar seu arquivo .env com a chave de verificação do webhook correta.
Este boilerplate usa saída estática com rotas de API sob demanda. Você precisa instalar um adapter para implantação:Veja os guias de implantação do Astro para detalhes.

​
Saiba Mais

​
Suporte

Precisa de ajuda com o boilerplate?