> ## 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.
# FastAPI Boilerplate
> Comece rapidamente com nosso boilerplate FastAPI para integrar Dodo Payments em suas aplicações backend Python
Boilerplate completo FastAPI + Dodo Payments
## Visão Geral
O boilerplate FastAPI fornece um ponto de partida pronto para produção para integrar Dodo Payments com seu backend Python. Este template inclui gerenciamento de sessão de checkout, verificação de webhook, integração de portal do cliente e padrões de API assíncronos para ajudá-lo a começar a aceitar pagamentos rapidamente.
Este boilerplate utiliza FastAPI com padrões async/await, Pydantic para validação e o SDK Python `dodopayments` para integração perfeita com a API.
### Recursos
* **Configuração Rápida** - Comece em menos de 5 minutos
* **Suporte Assíncrono** - Construído com os padrões nativos async/await do FastAPI
* **Sessões de Checkout** - Fluxo de checkout pré-configurado usando o SDK Python
* **Gerenciamento de Webhook** - Endpoint de webhook seguro com verificação de assinatura
* **Portal do Cliente** - Criação fácil de sessão do portal do cliente
* **Segurança de Tipo** - Validação completa do Pydantic e dicas de tipo
* **Configuração de Ambiente** - Configuração de variáveis de ambiente pronta para uso
## Pré-requisitos
Antes de começar, certifique-se de que você tem:
* **Python 3.9+** (recomendado: Python 3.11+)
* **pip** ou **uv** para gerenciamento de pacotes
* **Conta Dodo Payments** (para acessar as chaves da API e Webhook no painel)
## Início Rápido
```bash theme={null}
git clone https://github.com/dodopayments/fastapi-boilerplate.git
cd fastapi-boilerplate
```
Configure um ambiente Python isolado:
```bash theme={null}
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
Ou usando uv para gerenciamento de dependências mais rápido:
```bash theme={null}
uv venv
source .venv/bin/activate
```
```bash theme={null}
pip install -r requirements.txt
```
Ou com uv:
```bash theme={null}
uv pip install -r requirements.txt
```
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)
Certifique-se de estar no **Modo de Teste** enquanto desenvolve!
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_ENVIRONMENT=test_mode
```
Nunca comite seu arquivo `.env` no controle de versão. Ele já está incluído em `.gitignore`.
```bash theme={null}
uvicorn main:app --reload
```
Abra [http://localhost:8000/docs](http://localhost:8000/docs) para ver a documentação interativa da API!
Você deve ver a interface Swagger UI do FastAPI com todos os endpoints disponíveis prontos para testar.
## Estrutura do Projeto
```text theme={null}
fastapi-boilerplate/
├── main.py # FastAPI application entry point
├── routers/
│ ├── checkout.py # Checkout session endpoints
│ ├── webhook.py # Webhook handler endpoint
│ └── customer_portal.py # Customer portal endpoints
├── config.py # Environment configuration
├── requirements.txt # Python dependencies
├── .env.example # Environment template
└── README.md
```
## Endpoints da API
O boilerplate inclui os seguintes endpoints pré-configurados:
| Endpoint | Método | Descrição |
| ------------------ | ------ | ----------------------------------- |
| `/checkout` | POST | Criar uma nova sessão de checkout |
| `/webhook` | POST | Lidar com webhooks do Dodo Payments |
| `/customer-portal` | POST | Gerar URL do portal do cliente |
## Exemplos de Código
### Criando uma Sessão de Checkout
```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings
router = APIRouter()
dodo = AsyncDodoPayments(
bearer_token=settings.DODO_PAYMENTS_API_KEY,
environment=settings.DODO_PAYMENTS_ENVIRONMENT
)
class CheckoutRequest(BaseModel):
product_id: str
quantity: int = 1
customer_email: str | None = None
customer_name: str | None = None
@router.post("/checkout")
async def create_checkout(request: CheckoutRequest):
try:
session = await dodo.checkout_sessions.create(
product_cart=[{
"product_id": request.product_id,
"quantity": request.quantity
}],
customer={
"email": request.customer_email,
"name": request.customer_name
} if request.customer_email else None,
return_url="http://localhost:8000/success"
)
return {"checkout_url": session.checkout_url, "session_id": session.session_id}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
```
### Manipulando Webhooks
```python theme={null}
from fastapi import APIRouter, Request, HTTPException
import hmac
import hashlib
from config import settings
router = APIRouter()
def verify_webhook_signature(payload: bytes, signature: str) -> bool:
expected = hmac.new(
settings.DODO_PAYMENTS_WEBHOOK_KEY.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
@router.post("/webhook")
async def handle_webhook(request: Request):
payload = await request.body()
signature = request.headers.get("webhook-signature", "")
if not verify_webhook_signature(payload, signature):
raise HTTPException(status_code=401, detail="Invalid signature")
event = await request.json()
event_type = event.get("type")
match event_type:
case "payment.succeeded":
# Handle successful payment
payment_id = event["data"]["payment_id"]
print(f"Payment succeeded: {payment_id}")
case "subscription.active":
# Handle subscription activation
subscription_id = event["data"]["subscription_id"]
print(f"Subscription activated: {subscription_id}")
case "refund.succeeded":
# Handle refund
refund_id = event["data"]["refund_id"]
print(f"Refund processed: {refund_id}")
return {"status": "received"}
```
### Integração do Portal do Cliente
```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings
router = APIRouter()
dodo = AsyncDodoPayments(
bearer_token=settings.DODO_PAYMENTS_API_KEY,
environment=settings.DODO_PAYMENTS_ENVIRONMENT
)
class PortalRequest(BaseModel):
customer_id: str
@router.post("/customer-portal")
async def create_portal_session(request: PortalRequest):
try:
session = await dodo.customers.customer_portal.create(
customer_id=request.customer_id,
)
return {"portal_url": session.link}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
```
## Eventos de Webhook
O boilerplate demonstra o manuseio de eventos comuns de webhook:
| Evento | Descrição |
| ------------------------ | -------------------------------- |
| `payment.succeeded` | Pagamento concluído com sucesso |
| `payment.failed` | Tentativa de pagamento falhou |
| `subscription.active` | Assinatura agora está ativa |
| `subscription.cancelled` | Assinatura foi cancelada |
| `refund.succeeded` | Reembolso processado com sucesso |
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
* Prover 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/webhook
```
## Implantação
### Docker
```dockerfile theme={null}
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
Construa e execute:
```bash theme={null}
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo
```
### Considerações de Produção
Antes de implantar em produção:
* Altere `DODO_PAYMENTS_ENVIRONMENT` para `live_mode`
* Use chaves de API de produção do painel
* Atualize a URL do webhook para o seu domínio de produção
* Ative HTTPS para todos os endpoints
## Solução de Problemas
Certifique-se de que seu ambiente virtual esteja ativado e as dependências instaladas:
```bash theme={null}
source venv/bin/activate
pip install -r requirements.txt
```
**Causas comuns:**
* ID do produto inválido – verifique se existe no seu painel da Dodo
* Chave de API ou configuração de ambiente incorreta em `.env`
* Verifique os logs do FastAPI para mensagens de erro detalhadas
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 da 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.
* Garanta que `DODO_PAYMENTS_WEBHOOK_KEY` esteja configurado corretamente em seu `.env`
* Verifique se você está usando o corpo bruto da requisição para verificação de assinatura
* Confira se você está lendo corretamente o cabeçalho `webhook-signature`
## Saiba Mais
Documentação completa do SDK Python com suporte async
Saiba sobre todos os eventos de webhook e melhores práticas
Mergulhe na configuração da sessão de checkout
Documentação completa da API da Dodo Payments
## 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/fastapi-boilerplate) para problemas e atualizações
* Entre em contato com nossa [equipe de suporte](mailto:support@dodopayments.com) para assistência