Relatório de Orçamento Diário

É um projeto que consiste em um dashboard em Streamlit para acompanhar o orçamento diário de campanhas no Meta Ads e Google Ads, com uma camada opcional de API REST em FastAPI.

Dashboard Streamlit:

• Lista contas de anúncio do business (filtradas por META_BUSINESS_ID)
• Compara o gasto de hoje com o limite diário (padrão R$ 2.500)
• Exibe por campanha: orçamento diário, gasto, saldo restante, % usado, status, objetivo e métricas (impressões, cliques, CPC, CPM, CTR)
• Período configurável (hoje, ontem, 7/14/30 dias, mês, trimestre)

API REST (FastAPI):

• /health - Verificação
• /api/ad-accounts - Contas Meta Ads
• /api/campaigns - Campanhas Meta Ads
• /api/campaign-stats - Métricas Meta Ads
• /api/ad-sets - Ad sets Meta Ads
• /api/budget-report - Relatório Meta Ads
• /api/google/* - Endpoints equivalentes para Google Ads

├── .env.example          # Template de variáveis de ambiente
├── .gitignore
├── api.py                # API REST FastAPI
├── app.py                # Dashboard Streamlit
├── google_ads_client.py  # Cliente Google Ads API
├── meta_ads_client.py    # Cliente Meta Marketing API
└── requirements.txt      # Dependências Python

Meta Ads:

• META_BUSINESS_ID, META_AD_ACCOUNT_ID, META_DAILY_SPEND_LIMIT
• META_APP_ID, META_APP_SECRET, META_ACCESS_TOKEN (com permissão ads_read)

Google Ads:

• GOOGLE_DAILY_SPEND_LIMIT, GOOGLE_ADS_CUSTOMER_ID, GOOGLE_ADS_LOGIN_CUSTOMER_ID
• GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN

Execução

# Dashboard
streamlit run app.py

# API REST
uvicorn api:app --reload --port 8000

Documentação interativa da API: http://localhost:8000/docs

Segurança

Nunca commitar o arquivo .env com credenciais reais, e restringir allow_origins no api.py antes de expor a API publicamente.

Notas Técnicas

• Orçamentos Meta vêm em minor units e são convertidos para a moeda principal
• Campanhas com orçamento no nível de ad set somam os ad sets ativos
• Dados de "hoje" podem sofrer atraso de processamento nas plataformas

Desafio: Centralizar e automatizar o acompanhamento diário do orçamento de campanhas no Meta Ads e Google Ads, permitindo visibilidade em tempo real do gasto vs. limite definido, com alertas de estouro e métricas de performance por campanha.

Solução: Dashboard em Streamlit + API REST em FastAPI que consome as APIs do Meta Marketing e Google Ads, exibindo o orçamento diário, gasto, saldo restante e métricas de desempenho — com períodos configuráveis e cache local para reduzir chamadas às plataformas.

Principais ganhos:

• Controle financeiro: Comparação automática do gasto de hoje com o limite diário (META_DAILY_SPEND_LIMIT / GOOGLE_DAILY_SPEND_LIMIT), com barra de progresso visual.
• Agilidade na tomada de decisão: Períodos pré-definidos (hoje, ontem, 7/14/30 dias, mês, trimestre) permitem análises rápidas sem exportar dados.
• Escalabilidade: A API REST permite integrar os dados a outros sistemas (CRM, BI, alertas automaticos) sem depender do dashboard.
• Multi-plataforma: Unifica Meta Ads e Google Ads em uma única interface, reduzindo a fragmentação de ferramentas.

Arquitetura:

Dashboard Streamlit

• Listagem de contas de anúncio filtradas pelo META_BUSINESS_ID
• Comparativo do gasto de hoje vs. limite diário da empresa (padrão R$ 2.500)
• Métricas por campanha: orçamento diário, gasto, saldo restante, % usado, status, objetivo, impressões, cliques, CPC, CPM, CTR
• Seletor de período: hoje, ontem, 7/14/30 dias, mês atual, trimestre atual
• Atualização sob demanda via barra lateral

API REST (FastAPI)

Exemplos de uso:

curl "http://localhost:8000/api/budget-report?ad_account_id=act_123&date_preset=today"
curl "http://localhost:8000/api/google/budget-report?date_preset=last_7d"

Documentação interativa disponível em http://localhost:8000/docs (Swagger UI).

Meta Ads (Meta Marketing API)

1. Criar um App no Meta for Developers

   • Acesse developers.facebook.com e faça login com sua conta do Facebook
   • Clique em Meus Apps → Criar App
   • Selecione o tipo Empresa (Business) e siga as instruções
   • Anote o App ID e o App Secret (em Configurações → Básico)

2. Obter o Business Manager ID

   • Acesse business.facebook.com
   • Vá em Configurações do Negócio → Informações do Negócio
   • Copie o ID do Business Manager

3. Gerar o Access Token

   • No painel do app, vá em Ferramentas → Graph API Explorer
   • Selecione seu app no dropdown
   • Clique em Gerar Token de Acesso
   • Marque as permissões: ads_read e business_management
   • Copie o token gerado

4. Obter o Ad Account ID

   • No Gerenciador de Anúncios, o ID aparece no formato act_XXXXXXXXX
   • Ou via Graph API Explorer: GET /me/adaccounts

5. Para token de longa duração (System User)

   • No Business Manager, vá em Usuários → Usuários do Sistema
   • Crie um system user e gere um token permanente com as permissões acima

Variáveis no .env:

META_BUSINESS_ID=seu_business_id
META_AD_ACCOUNT_ID=act_123456789
META_DAILY_SPEND_LIMIT=2500
META_APP_ID=seu_app_id
META_APP_SECRET=seu_app_secret
META_ACCESS_TOKEN=seu_access_token

Google Ads (Google Ads API)

1. Criar um Projeto no Google Cloud Console

   • Acesse console.cloud.google.com

• Crie um novo projeto (ex: "ChefBob Ads Budget")
• Ative a Google Ads API em APIs e Serviços → Biblioteca

2. Criar Credenciais OAuth 2.0

   • Vá em APIs e Serviços → Credenciais
   • Clique em Criar Credenciais → ID do cliente OAuth
   • Tipo: Aplicativo da Web
   • Anote o Client ID e o Client Secret

3. Obter o Developer Token

   • Acesse ads.google.com com a conta de administrador (MCC)
   • Vá em Ferramentas e Configurações → API Center
   • Solicite o Developer Token (aprovação pode levar alguns dias)
   • Anote o token

4. Gerar o Refresh Token

   • Use o OAuth 2.0 Playground

• Clique na engrenagem → marque Use your own OAuth credentials
• Insira Client ID e Client Secret

• Autorize o escopo: https://www.googleapis.com/auth/adwords

• Troque o código de autorização por tokens e copie o Refresh Token

5. Obter o Customer ID

   • No canto superior direito do Google Ads, copie o ID no formato XXX-XXX-XXXX
   • Se usar MCC, o Login Customer ID é o ID da conta de administrador

Variáveis no .env:

GOOGLE_DAILY_SPEND_LIMIT=2500
GOOGLE_ADS_CUSTOMER_ID=1234567890
GOOGLE_ADS_LOGIN_CUSTOMER_ID=0987654321
GOOGLE_ADS_DEVELOPER_TOKEN=seu_developer_token
GOOGLE_ADS_CLIENT_ID=seu_client_id.apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET=seu_client_secret
GOOGLE_ADS_REFRESH_TOKEN=seu_refresh_token

Instalação e Execução

git clone https://github.com/reulison/Ads-Budget-Dayli
Set-Location "Ads Budget Dayli"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
# Preencha o .env com as credenciais obtidas acima

Rodar o Dashboard:

streamlit run app.py

Acesse http://localhost:8501.

Rodar a API REST:

uvicorn api:app --reload --port 8000

Documentação em http://localhost:8000/docs.

Segurança e Boas Práticas

• Nunca commite o .env — o .gitignore já exclui .env, cache.json, .venv/ e .streamlit/
• Use apenas o .env.example como referência pública, com valores vazios
• Revogue e regenere credenciais imediatamente se um token for exposto
• Restrinja allow_origins em api.py antes de expor a API publicamente (por padrão, aceita qualquer origem para desenvolvimento local)
• Para produção, prefira System User tokens (Meta) e Service Accounts (Google) em vez de tokens de usuário.

O Ads Budget Daily nasceu da necessidade real da ChefBob de controlar o investimento em mídia paga de forma ágil e precisa. Ao unificar Meta Ads e Google Ads em um único dashboard e expor os dados via API REST, o projeto elimina trabalho manual, reduz o risco de estouro de orçamento e libera o time para focar no que realmente importa: escalar campanhas que trazem resultado.

Link do repositório: github.com/reulison/Ads-Budget-Dayli

Stack: Python, Streamlit, FastAPI, Meta Marketing API, Google Ads API, Uvicorn, python-dotenv.