Astro Minimal Boilerplate - Dodo Payments Documentation

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

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

Inscreva-se em Dodo Payments e obtenha suas credenciais no painel:

Chave da API: Painel → Desenvolvedor → Chaves da API
Chave do Webhook: Painel → Desenvolvedor → Webhooks

Certifique-se de estar no Modo de Teste durante o desenvolvimento!

Configure Environment Variables

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 faça commit de seu arquivo .env no controle de versão. Ele já está incluído em .gitignore.

Add Your Products

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

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

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:

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:

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:

Plataforma	Guia
Vercel	Implantar no Vercel
Netlify	Implantar no Netlify
Cloudflare	Implantar 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 o seu domínio implantado.

Solução de Problemas

Module not found or build errors

Exclua node_modules e reinstale as dependências:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

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

Webhooks not receiving events

Para testes locais, use ngrok para expor seu servidor:

ngrok http 4321

Atualize a URL do webhook no seu painel Dodo para a URL do ngrok. Lembre-se de atualizar seu arquivo .env com a chave de verificação do webhook correta.

Customer portal link doesn't work

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.

Build fails with adapter error

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 para mais detalhes.

Saiba Mais

Suporte

Precisa de ajuda com o boilerplate?

Junte-se à nossa comunidade no Discord para perguntas e discussões
Verifique o repositório do GitHub para problemas e atualizações
Entre em contato com nossa equipe de suporte para assistência

​Visão Geral

​Recursos

​Pré-requisitos

​Início Rápido

​Estrutura do Projeto

​Personalização

​Atualizar Informações do Produto

​Pré-preencher Dados do Cliente

​Atualizar Portal do Cliente

​Eventos de Webhook

​Implantação

​Atualizar URL do Webhook

​Solução de Problemas

​Saiba Mais

​Suporte

Visão Geral

Recursos

Pré-requisitos

Início Rápido

Estrutura do Projeto

Personalização

Atualizar Informações do Produto

Pré-preencher Dados do Cliente

Atualizar Portal do Cliente

Eventos de Webhook

Implantação

Atualizar URL do Webhook

Solução de Problemas

Saiba Mais

Suporte