Skip to content

Variáveis de Ambiente por Ambiente

Referência completa de todas as variáveis de ambiente organizadas por serviço e ambiente (development/preview/production).

Tabela Completa

Backend (backend/.env)

Variável Desenvolvimento Preview Produção Obrigatória
SUPABASE_URL URL do projeto dev URL do projeto preview URL do projeto prod Sim
SUPABASE_SERVICE_ROLE_KEY service_role dev service_role preview service_role prod Sim
SUPABASE_JWT_SECRET JWT secret dev JWT secret preview JWT secret prod Sim
ASAAS_API_KEY Chave sandbox Chave sandbox Chave produção Sim
ASAAS_WEBHOOK_SECRET Qualquer string Secret sandbox Secret produção Sim
ASAAS_BASE_URL https://sandbox.asaas.com/api/v3 https://sandbox.asaas.com/api/v3 https://api.asaas.com/v3 Sim
ORS_API_KEY Sua chave gratuita Sua chave gratuita Chave produção Sim
VAPID_PRIVATE_KEY Gerado localmente Mesmo de dev Chave produção Sim
NEXT_PUBLIC_VAPID_PUBLIC_KEY Par da private key Par da private key Par de produção Sim
VAPID_SUBJECT mailto:dev@local.com mailto:dev@local.com mailto:suporte@fastdeliv.com.br Sim
FRONTEND_URL http://localhost:3000 URL de preview https://fast-deliv.vercel.app Sim

Frontend (frontend/.env.local)

Variável Desenvolvimento Preview Produção Obrigatória
NEXT_PUBLIC_SUPABASE_URL URL do projeto dev URL do projeto preview URL do projeto prod Sim
NEXT_PUBLIC_SUPABASE_ANON_KEY anon key dev anon key preview anon key prod Sim
NEXT_PUBLIC_API_URL http://localhost:8000 URL do backend preview https://fast-deliv-backend.vercel.app Sim
NEXT_PUBLIC_VAPID_PUBLIC_KEY Mesma do backend Mesma do backend Mesma do backend Sim
NEXT_PUBLIC_STADIA_API_KEY Sua chave gratuita Sua chave gratuita Chave produção Sim

Detalhes por Variável

SUPABASE_URL

  • Onde encontrar: Dashboard > Settings > API > Project URL
  • Formato: https://xxxxxxxxxxxxxxxxxxx.supabase.co
  • Segurança: Pode ser exposta no frontend (prefixo NEXT_PUBLIC_)

SUPABASE_SERVICE_ROLE_KEY

  • Onde encontrar: Dashboard > Settings > API > service_role secret
  • Formato: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (JWT)
  • Segurança: NUNCA expor no frontend — bypassa RLS completamente

SUPABASE_JWT_SECRET

  • Onde encontrar: Dashboard > Settings > API > JWT Settings > JWT Secret
  • Formato: String aleatória de 32+ caracteres
  • Uso: Backend valida tokens JWT dos usuários

NEXT_PUBLIC_SUPABASE_ANON_KEY

  • Onde encontrar: Dashboard > Settings > API > anon public
  • Formato: JWT longo
  • Segurança: Seguro para expor — RLS garante a segurança dos dados

ASAAS_API_KEY

  • Sandbox: $aact_YTU5YTE0M2M2N2I4MTliNzk0YTI5N2U5MjY0OWMwMGY6OjI...
  • Produção: Chave diferente obtida no dashboard ASAAS
  • Segurança: NUNCA expor no frontend

ASAAS_WEBHOOK_SECRET

  • Como gerar: Qualquer string segura (use openssl rand -hex 32)
  • Uso: Validação HMAC-SHA256 dos webhooks recebidos
  • Configuração: Mesma string configurada no dashboard ASAAS ao criar o webhook

ASAAS_BASE_URL

  • Sandbox: https://sandbox.asaas.com/api/v3
  • Produção: https://api.asaas.com/v3

ORS_API_KEY

  • Onde obter: openrouteservice.org/dev
  • Limite: 2000 requisições/dia (plano gratuito)
  • Uso: Cálculo de rotas ao criar entregas

VAPID_PRIVATE_KEY / NEXT_PUBLIC_VAPID_PUBLIC_KEY

  • Como gerar: 
    npx web-push generate-vapid-keys
# Public Key: BHf...  → NEXT_PUBLIC_VAPID_PUBLIC_KEY
# Private Key: abc... → VAPID_PRIVATE_KEY
  • Importante: Um par de chaves por ambiente (nunca reutilizar entre prod e dev)

NEXT_PUBLIC_STADIA_API_KEY

  • Onde obter: stadiamaps.com (gratuito até 200k tiles/mês)
  • Formato: UUID sem hífens

Scripts de Configuração

Configurar backend na Vercel (produção)

cd backend

# Supabase
vercel env add SUPABASE_URL production <<< "https://xxx.supabase.co"
vercel env add SUPABASE_SERVICE_ROLE_KEY production
vercel env add SUPABASE_JWT_SECRET production

# ASAAS
vercel env add ASAAS_API_KEY production
vercel env add ASAAS_WEBHOOK_SECRET production
vercel env add ASAAS_BASE_URL production <<< "https://api.asaas.com/v3"

# Outros
vercel env add ORS_API_KEY production
vercel env add VAPID_PRIVATE_KEY production
vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY production
vercel env add VAPID_SUBJECT production <<< "mailto:suporte@fastdeliv.com.br"
vercel env add FRONTEND_URL production <<< "https://fast-deliv.vercel.app"

Configurar frontend na Vercel (produção)

cd frontend

vercel env add NEXT_PUBLIC_SUPABASE_URL production
vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY production
vercel env add NEXT_PUBLIC_API_URL production <<< "https://fast-deliv-backend.vercel.app"
vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY production
vercel env add NEXT_PUBLIC_STADIA_API_KEY production

Validação de Ambiente

Para verificar se todas as variáveis obrigatórias estão configuradas, o backend usa Pydantic Settings com Field(..., alias="VAR_NAME"). Campos sem default lançam ValidationError na inicialização se não encontrados.

# backend/app/core/config.py
class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

    supabase_url: str = Field(..., alias="SUPABASE_URL")          # obrigatório
    asaas_base_url: str = Field(
        default="https://api.asaas.com/v3",
        alias="ASAAS_BASE_URL"
    )  # tem default

Se uma variável obrigatória estiver faltando, o servidor não inicia e exibe: 

pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings
SUPABASE_URL
  Field required [type=missing, ...]

Checklist por Ambiente

Desenvolvimento

  • [ ] backend/.env criado com todas as variáveis
  • [ ] frontend/.env.local criado com todas as variáveis
  • [ ] ASAAS_BASE_URL apontando para sandbox
  • [ ] FRONTEND_URL=http://localhost:3000
  • [ ] NEXT_PUBLIC_API_URL=http://localhost:8000

Preview (Pull Requests)

  • [ ] Variáveis configuradas para ambiente preview na Vercel
  • [ ] ASAAS_BASE_URL apontando para sandbox
  • [ ] FRONTEND_URL apontando para a URL de preview do frontend

Produção

  • [ ] Variáveis configuradas para ambiente production na Vercel
  • [ ] ASAAS_BASE_URL=https://api.asaas.com/v3
  • [ ] ASAAS_API_KEY é a chave de produção (não sandbox)
  • [ ] FRONTEND_URL apontando para domínio de produção
  • [ ] NEXT_PUBLIC_API_URL apontando para backend de produção
  • [ ] Webhook ASAAS configurado para URL de produção