Ferramentas externas e credenciais

Esta página explica como funciona a parte técnica de usar ferramentas externas (Apollo, YouTube API, Cloudflare, etc.) em projetos do grupo — e como você, membro do time, consegue acesso.

Pra ver a lista completa de ferramentas que o grupo já usa, veja Ferramentas do grupo.

---

O princípio central

Código ≠ credencial.

• Código (versionado no Git, compartilhado com o time): lógica, chamadas de API, estrutura
• Credencial (nunca no Git, mora onde o código roda): API key, token, senha

Regra inegociável: credencial nunca entra no Git. Nem commit, nem .env commitado, nem hardcoded no código.

---

Onde o código roda — 3 ambientes

Toda credencial vive onde o código roda. São 3 ambientes possíveis:

1. Dev local (máquina do dev)

Quando você (dev) roda o código na tua máquina.

Onde a credencial mora: arquivo .env na pasta do projeto na tua máquina. Nunca esse .env vai pro Git — .gitignore protege.

Exemplo:

~/ventures/emotion-studios/1bmg/outbound/.env

APOLLO_API_KEY=sua-chave-dev-ou-mock-aqui
PIPEDRIVE_TOKEN=sua-chave-dev

2. Produção (hosting)

Quando o código tá no ar, servindo usuários, rodando em Cloudflare Pages / Workers / Netlify / etc.

Onde a credencial mora: painel da plataforma de hospedagem (environment variables).

Exemplo: claimradar.pages.dev (Cloudflare Pages):

• Dashboard → Pages → claimradar → Settings → Environment variables
• Lá tem YOUTUBE_API_KEY, CONTENT_ID_KEY (valores criptografados)
• Quando um usuário acessa o site, Cloudflare injeta as variáveis no runtime

3. Automação (GitHub Actions)

Quando o código roda automaticamente via cron ou trigger.

Onde a credencial mora: Settings → Secrets and variables → Actions do repo no GitHub.

Exemplo: cron do SDR (se migrar pra Actions):

• Secret APOLLO_API_KEY configurado no repo
• Workflow .github/workflows/sdr-daily.yml lê o secret via ${{ secrets.APOLLO_API_KEY }}
• Action roda, chama Apollo, loga resultado

Resumo visual

┌─────────────────────────┐
│  CÓDIGO (GitHub)        │
│  Sem credenciais         │
└───────────┬─────────────┘
            │ clone / deploy
            │
  ┌─────────┴──────────┬─────────────────┐
  ▼                    ▼                 ▼
Dev local          Produção          Automação
 .env local        Env vars do       Secrets do
 na pasta          hosting (CF)      GitHub Actions
  │                    │                 │
  └────────────────────┴─────────────────┘
         CADA UM tem sua cópia
         da credencial, isolada

---

Como você (time) consegue acesso

Modelo: reativo. Você pede quando precisar. Fred libera caso a caso.

Fluxo pra pedir

1. Você tá numa tarefa que precisa de acesso a X
2. Tenta primeiro sem credencial:
   • Mocks/fixtures (arquivos em tests/fixtures/)
   • Docs da API (endpoints sem chave)
   • Só leitura de código
3. Se ainda precisar, abre Issue no repo da empresa:

TÍTULO: [Acesso] <Ferramenta> pra <tarefa>
LABEL: access-request

## Ferramenta
<Apollo / YouTube API / Cloudflare / etc.>

## Tarefa relacionada
<link do Jira / descrição da tarefa>

## O que vou fazer
<ex: "debugar paginação do SDR local, rodar 5-10 requests pra validar fix">

## Já tentei
<mock? fixtures? explicou por que não serve>

4. Fred recebe notificação, responde na janela de revisão (9h-10h)
5. Libera via uma das 5 formas abaixo

---

Os 5 padrões de liberação

Fred escolhe o padrão em função do serviço e do caso de uso.

Padrão A — Seat multi-usuário (o mais simples)

Algumas ferramentas permitem múltiplos usuários na mesma conta paga. Você vira member do workspace e acessa com email próprio.

Quando: UI-based (Apollo, PipeDrive, Cloudflare dashboard, Notion, Jira)

Resposta típica do Fred:

“Convidei você em Apollo. Verifica teu email @emotionstudios.com.br e aceita.”

O que você faz: abre a ferramenta, loga com email corporativo, usa UI normalmente. Nada no .env.

Padrão B — Chave dev (free tier / sandbox)

Você cria sua própria conta (plano free) da ferramenta, pega API key dela, coloca no .env local. Ou Fred cria um dev seat limitado pra você.

Quando: você precisa da API direta, e a conta principal é cara/crítica

Resposta típica do Fred:

“Cria conta free no Apollo com teu email, pega a key. Coloca no .env local. Pra produção, já tá configurada — não te preocupa.”

O que você faz:

1. Cria conta free pessoal
2. Pega API key
3. Copia pro .env local
4. Roda

Se vazar a chave: zero impacto (é tua, free, limitada).

Padrão C — Mock / fixtures (sem credencial real)

Você não usa a API real — usa dados falsos gravados.

Quando: testar lógica de parsing, transformação, layout

Resposta típica do Fred:

“Não precisa de chave. Usa os mocks em tests/fixtures/apollo-sample.json.”

O que você faz:

# em vez de chamar Apollo:
response = json.load(open("tests/fixtures/apollo-sample.json"))
# mesmo teste de parsing, 0 credenciais

Padrão D — Proxy via Cloudflare Worker

Fred cria um worker que tem a credencial real. Você chama o worker com um token pessoal. Worker responde com os dados.

Quando: API key é muito sensível pra compartilhar (ex: BigQuery Service Account, token de Instagram com refresh)

Resposta típica do Fred:

“Criei proxy apollo-proxy.fred-valente.workers.dev. Teu token: xxx (vou passar por Signal). No .env coloca APOLLO_PROXY_URL e APOLLO_PROXY_TOKEN.”

O que você faz: usa o proxy em vez da API direta:

requests.get(
    f"{os.getenv('APOLLO_PROXY_URL')}/search",
    headers={"Authorization": f"Bearer {os.getenv('APOLLO_PROXY_TOKEN')}"}
)

Vantagem: Fred pode revogar teu token sem trocar a chave real.

Padrão E — GitHub Actions com secret

Você não roda local — trigga um workflow automatizado.

Quando: tarefas batch/cron que sempre rodam no mesmo ambiente

Resposta típica do Fred:

“Adicionei o secret APOLLO_API_KEY no repo. Abre /.github/workflows/sdr-daily.yml e roda gh workflow run sdr-daily.yml.”

O que você faz:

gh workflow run sdr-daily.yml --ref main
gh run watch  # acompanha

Workflow roda na nuvem do GitHub com a credencial injetada. Você nunca vê a key.

---

O cenário clássico: “Paulo vai dar manutenção no código do Apollo”

Aplicando o modelo:

1. Paulo abre o projeto 1bmg/outbound/sdr_engine.py
2. Lê e entende a lógica — não precisa de credencial nenhuma pra isso
3. Identifica o bug, edita o código
4. Pra testar:
   • Primeira tentativa: mocks em tests/fixtures/ (Padrão C)
   • Se precisar de requests reais: Paulo cria conta free Apollo + key própria (Padrão B)
5. Abre PR
6. Fred revisa, merge
7. Produção continua rodando com a chave real (que tá no .env do Fred ou em secret do GitHub Actions) — Paulo não toca nela

---

Regras de segurança

Inegociáveis

• ❌ Nunca commit credencial. grep -r "api.key\|secret\|token" . antes de cada commit.
• ❌ Nunca cole credencial em chat (WhatsApp, Telegram sem E2E, Slack). Use Signal ou 1Password share.
• ❌ Nunca mande credencial por email comum.
• ❌ Nunca rode git push --force em branch que teve credencial — não remove do histórico, só esconde.

Obrigatórias

• ✅ .env sempre no .gitignore.
• ✅ Antes de commit, checa git status — arquivo .env não pode aparecer.
• ✅ Se vazou: rotar imediatamente (gera nova chave, invalida antiga) + avisa Fred.
• ✅ Pra compartilhar credencial (casos raros): usa Signal ou 1Password Secure Share (link expira em 1 dia).

---

FAQ

”Posso subir .env.example pro Git?”

Sim. .env.example é template sem valores reais. Útil pra documentar quais variáveis o projeto precisa. Exemplo:

.env.example

APOLLO_API_KEY=          # pedir pro Fred via issue
PIPEDRIVE_TOKEN=         # pedir pro Fred via issue
CLOUDFLARE_ACCOUNT_ID=   # disponível na dashboard

“Rodei código local e vazei credencial sem querer”

1. Rota a chave imediatamente (faz nova, invalida a antiga)
2. Avisa Fred
3. Se chave tá no Git (mesmo em commit antigo), ainda precisa rotar — histórico do Git fica

”A credencial tá no repo de um projeto que eu clonei — posso usar?”

Nunca deveria acontecer. Se achou credencial commitada, avisa Fred imediatamente antes de fazer qualquer coisa. Rotação urgente.

”Preciso acessar a dashboard do Cloudflare pra ver logs do meu site”

Padrão A: Fred te convida como Member do Cloudflare. Loga com email corporativo, vê dashboard completo (com permissão específica).

”Não sei se a ferramenta que quero já existe no grupo”

Veja Ferramentas do grupo — catálogo completo. Se não tiver, abre Issue com proposta.