Setup — environment & toggles

Backend lê config de env vars. Toggle Omie mock × real, Bubble staging × prod, DB sqlite × postgres — tudo em runtime via env vars. Esta página: o que mudar, onde, como redeploy.

Effective config — produção atual

Var	Valor atual (staging)	O que faz
APP_ENV	production	Sentry/log gating
APP_PORT	8000	Porta uvicorn
BUBBLE_DATA_API_URL	https://eventos.blueprintt.co/version-test/api/1.1/obj	Staging Bubble. Trocar pra prod URL quando subir.
USE_OMIE_MOCK	true	Mock in-process (sem hit Omie real)
OMIE_BASE_URL	https://app.omie.com.br/api/v1	Endpoint real (só usado se USE_OMIE_MOCK=false)
DATABASE_URL	sqlite:////data/blu_omie.db	SQLite no volume /srv/blu-omie-api/data (persiste entre deploys)
ENABLE_TEST_API	YES	/v1/test/* ativo (NÃO ativar em prod produtiva)

Secrets (não exibidos): BUBBLE_API_KEY, BUBBLE_TO_API_BEARER, OMIE_APP_KEY_AABC, OMIE_APP_SECRET_AABC, OMIE_APP_KEY_LNG, OMIE_APP_SECRET_LNG.

Note

Live: blu-omie-api.fonsecagabriel.com.br/health/full retorna mode atual + versão. Confirma o que tá no ar.

Switch Omie: mock ↔ real

Mock (default)

Backend usa SDK in-process (omie-sdk-mock). Não bate na Omie. Boa pra demo, integration tests, dev Bubble experimentando.

backend/config/deploy.yml

env:
  clear:
    USE_OMIE_MOCK: "true"

Sem necessidade de OMIE_APP_KEY_* ou OMIE_APP_SECRET_* válidos (mock ignora). Os placeholders mock-key-aabc etc estão setados via .kamal/secrets.

Redeploy: cd backend && kamal redeploy.

Real (AABC produtivo)

Backend bate na Omie real via SDK. Requer app produtivo AABC com OMIE_APP_KEY_AABC + OMIE_APP_SECRET_AABC válidos (Confluence 3812884488).

1. Editar backend/config/deploy.yml — flip USE_OMIE_MOCK: "false" e confirmar OMIE_BASE_URL: "https://app.omie.com.br/api/v1".

   env:
     clear:
       USE_OMIE_MOCK: "false"
       OMIE_BASE_URL: "https://app.omie.com.br/api/v1"

2. Exportar credenciais reais:

   export OMIE_APP_KEY_AABC=...
   export OMIE_APP_SECRET_AABC=...
   export KAMAL_REGISTRY_PASSWORD=$(gh auth token)

3. Redeploy — cd backend && kamal redeploy (~3 min).

4. Verificar mode no ar:

   curl https://blu-omie-api.fonsecagabriel.com.br/health/full | jq '.omie_mode'
   # → "real"

⚠ Rate-limit Omie real: HTTP 425 = ban 31min, REDUNDANT = wait hint + 5s. Backend SDK já tem throttle + recovery (Lane A em PR #11). Mesmo assim — não martelar em produção sem necessidade.

⚠ Aplicativo Teste de Demonstração (alternativa pra smoke seguro): grátis, 7d renovável via ajuda@omie.com.br, dados fictícios pré-populados. Use OMIE_APP_KEY_* desse app pra rodar make smoke-real sem afetar app produtivo.

Apenas para AABC ↔ trocar LNG

LNG está fora do escopo Versão Atual (Confluence 3813310465). Não usar em runtime. Variáveis existem só pra não quebrar config schema.

Decisão: ADR-1 em Decisions.

Switch Bubble: staging ↔ produção

# backend/config/deploy.yml — clear
BUBBLE_DATA_API_URL: https://eventos.blueprintt.co/version-test/api/1.1/obj   # staging
# BUBBLE_DATA_API_URL: https://eventos.blueprintt.co/api/1.1/obj              # produção (when ready)

BUBBLE_API_KEY é secret separado. Geralmente staging + prod usam keys diferentes — trocar via export BUBBLE_API_KEY=<prod-key> antes do kamal redeploy.

Switch DB: sqlite ↔ postgres

SQLite (default produção atual)

env:
  clear:
    DATABASE_URL: sqlite:////data/blu_omie.db
volumes:
  - "/srv/blu-omie-api/data:/data"

Persiste no host VPS em /srv/blu-omie-api/data/blu_omie.db. Não dropa em redeploy. Backup via ssh root@62.171.145.76 'cat /srv/blu-omie-api/data/blu_omie.db' > backup.db.

Postgres accessory

Pra volume > sqlite confortável (~10GB+ ou multi-region), provisionar Postgres como Kamal accessory:

backend/config/deploy.yml

accessories:
  db:
    image: postgres:16
    host: 62.171.145.76
    port: "127.0.0.1:5432:5432"
    env:
      secret:
        - POSTGRES_PASSWORD
    volumes:
      - /var/lib/postgresql/data:/var/lib/postgresql/data

env:
  clear:
    DATABASE_URL: postgresql+psycopg://blu_omie:${POSTGRES_PASSWORD}@127.0.0.1:5432/blu_omie

Comandos:

kamal accessory boot db        # provisiona container postgres no VPS
kamal accessory exec db psql   # shell SQL

Migrar sqlite → postgres: dump → restore via alembic upgrade head no novo target. Não há automation pronta.

Smoke local com ngrok (Bubble dev)

Pra apontar Bubble staging pro backend local (dev), sem redeploy:

1. Rodar backend local — cd backend && make dev (uvicorn em :8000 com USE_OMIE_MOCK=true por default em .env).

2. Expor via ngrok — ngrok http 8000. Copy URL https://abc123.ngrok-free.app.

3. Trocar base URL no Bubble API Connector — substituir https://blu-omie-api.fonsecagabriel.com.br pela URL ngrok.

4. Disparar pedido de teste no Bubble staging. Backoffice pessoal evita poluir tickets reais.

5. Observar logs — terminal do uvicorn mostra request entrando. Postgres local persiste em sqlite tmp (dev).

6. Voltar pra staging Kamal — após terminar, trocar base URL de volta. Sem isso, clientes reais ficam batendo no seu laptop.

Ver também: Bubble Dev — Passo a passo.

Sandbox / ambiente demo Omie

TL;DR: não existe sandbox global na Omie. Toggle Homologação cobre só envelope NFS-e. Caminho oficial pra dev/smoke isolado = Aplicativo Teste de Demonstração (gratis, 7d renovável). Plano completo: BLU-765 (Backlog).

Por que não basta apontar pra app.omie.com.br/api/v1

Conta luiz.ribeiro@devmagic.com.br tem 2 apps produtivos: AABC (CNPJ 50.162.682/0001-07) + LNG (fora do escopo Versão Atual). Cliente/Projeto/OS/faturamento via API são lançamentos reais — vão pro banco da empresa. Toggle Homologação só protege envelope NFS-e; e tem pegadinha: algumas Prefeituras não suportam homologação → NFS-e “homologação” cai em produção real.

✅ Provado vivo (2026-06-04)

Criamos um sandbox via Playwright headed end-to-end na conta luiz.ribeiro@devmagic.com.br. Sandbox ativo agora:

• Nome: Blueprintt Integration Sandbox
• URL ERP: https://app.omie.com.br/gestao/blueprintt-erd42e40/
• Validade: 7 dias (renovar via ajuda@omie.com.br antes do vencimento)
• Dados: pré-populados (CRM, Vendas/NF-e, Serviços/NFS-e, Compras, Finanças, Painel Contador)

Click em “Acessar” abre o ERP completo com identidade BLUEPRINTT INTEGRATION SANDBOX (TRIAL):

API key não exposta auto na UI

Achado da exploração: a UI atual do Omie ERP não expõe app_key + app_secret diretamente após criar o app demo. O sandbox dá acesso ao ERP (UI + dados fictícios) mas as credenciais de API parecem requerer step adicional. Caminhos possíveis (ainda não confirmados):

1. Solicitar via ajuda@omie.com.br — pedir explicitamente app_key + app_secret pra este sandbox.
2. Portal externo developer.omie.com.br — pode existir interface separada pra gerenciar credenciais API.
3. Configurações > Integrações > Hub Apps dentro do ERP — submenu pode existir mas precisa exploração manual logada.

Próxima ação: Luiz pode logar manualmente em https://app.omie.com.br/gestao/blueprintt-erd42e40/ e navegar Configurações → Aplicativos ou similar pra encontrar as credenciais. Quando obtidas, atualizar deploy:

export OMIE_APP_KEY_AABC=<sandbox_key>
export OMIE_APP_SECRET_AABC=<sandbox_secret>
cd backend && kamal env push && kamal app boot

Caminho oficial — Aplicativo Teste de Demonstração

Item	Valor
Custo	R$ 0
Validade	7 dias (renovável via ajuda@omie.com.br)
Dados	Pré-populados (clientes/produtos/contas/serviços fictícios)
CNPJ	Não requer CNPJ próprio
API	Completa: app_key + app_secret
NFS-e	Funciona em modo homologação (sem valor fiscal)
Vars sugeridas	OMIE_APP_HML_KEY + OMIE_APP_HML_SECRET
Link oficial	Como criar — Omie Ajuda

1. Pedir o app demo — quem faz: ops/responsável Omie do time. Onde: portal Omie → Aplicativos → Criar Aplicativo de Teste. Resposta imediata.
2. Capturar app_key + app_secret — exportar como OMIE_APP_HML_KEY + OMIE_APP_HML_SECRET. Não commitar.
3. Configurar NFS-e em homologação — via UI da empresa demo (Configurações → Notas Fiscais → Ambiente). Como trocar ambiente NFS-e.
4. Validar conectividade — POST /geral/clientes/ com ListarClientes deve retornar 200. Se 425 → bypass abuse detection (esperar 31min).
5. Verificar com contador — confirmar que a Prefeitura do CNPJ fictício suporta homologação NFS-e antes do primeiro smoke (pegadinha).
6. Documentar processo de renovação — calendar event a cada 6 dias enviando mail pra ajuda@omie.com.br solicitando renovação por mais 7d. Definir responsável.

Roteiro de smoke E2E (10 passos do BLU-765)

1. Criar app de teste na Omie (sem CNPJ próprio)
2. Validar conectividade — POST ListarClientes
3. Configurar NFS-e em homologação na empresa fictícia
4. Cliente — POST /geral/clientes/ (criar via Customer Service)
5. OS — POST /servicos/os/
6. Faturamento — via Billing Service
7. Emissão NFS-e — POST /servicos/osp/ em modo homologação
8. Cancelamento NFS-e — POST /servicos/nfse/ action cancelar
9. Idempotência — repetir steps 4+5 com mesma chave, esperar dedup
10. Regra dia 25 — mock now = dia 26 + agendamento imediato

Riscos / pegadinhas

Caution

• Prefeituras sem homologação NFS-e — algumas não disponibilizam ambiente. “Homologação” cai em produção real + gera nota fiscal. Validar com contador antes do primeiro smoke.
• 7 dias = processo manual recorrente — precisa responsável claro pra evitar quebra de pipeline. Calendar event obrigatório.
• Rate-limit não distingue trial vs produtivo: 240 req/min · IP+AppKey+Método, 960 req/min · IP. 10 erros → ban HTTP 425 por 31min. REDUNDANT = cache por ID (60s). Detalhe oficial.
• CNPJ extra permanente — custo de “empresa demo” no plano não é documentado publicamente. Abrir ticket comercial Omie se quiser permanente pós-go-live.

Alternativas avaliadas

Caminho	Custo	Trade-off
App Teste de Demonstração ✅	R$ 0	7d renovação manual; recomendado (BLU-765)
Toggle Homologação no app AABC produtivo	R$ 0	Cobre só envelope NFS-e; Cliente/OS/Faturamento ainda hit real
omie-sdk-mock (in-process) ✅ default atual	R$ 0	Não vai pra Omie; ótimo pra unit/integration mas não cobre quirks reais
CNPJ próprio + plano Omie permanente	$$$ pago	Custo não documentado; só faz sentido pós-go-live
Plano Empresarial / Multi-CNPJ Blueprintt	depende	Verificar se cobre CNPJ extra sem custo (pendência alinhamento Luiz)
Sandbox API standalone Omie	∅	Não existe. Documentação oficial confirma

Status atual da integração

• Backend (blu-omie-api.fonsecagabriel.com.br) roda com USE_OMIE_MOCK=true — não bate na Omie real. Seguro.
• Pra ativar Omie real: criar app demo (BLU-765), exportar OMIE_APP_HML_KEY/SECRET, flip USE_OMIE_MOCK=false, redeploy.
• Credenciais AABC produtivas já registradas no Confluence: Ambientes, Credenciais e Configuração (Versão Atual) 3812818975. Usar só quando for produção real.

Reload runtime — kamal redeploy

# Mudou env clear (sem rebuild image)
cd backend && kamal env push && kamal app boot

# Mudou env secret (re-export antes)
export OMIE_APP_KEY_AABC=...
cd backend && kamal env push && kamal app boot

# Mudou Dockerfile / código
cd backend && kamal deploy

# Rollback pra versão anterior
cd backend && kamal rollback <versão_sha>

kamal app details mostra versão atual rodando. kamal app logs -f tail dos logs.

Endpoint pra checar config no ar

GET /health/full retorna:

{
  "status": "ok",
  "app_env": "production",
  "omie_mode": "mock",
  "omie_base_url": "https://app.omie.com.br/api/v1",
  "bubble_url": "https://eventos.blueprintt.co/version-test/api/1.1/obj",
  "db": "sqlite",
  "test_api_enabled": true,
  "version": "v0.1.0"
}

Use isto pra confirmar o estado depois de qualquer kamal env push ou redeploy — sem precisar SSH no VPS.

Tip

TL;DR: edita backend/config/deploy.yml, exporta secrets se mudou, roda kamal redeploy (ou kamal env push && kamal app boot se só env). GET /health/full confirma.

Incident triage — runbook

Três incidentes mais prováveis em produção, com triagem rápida. Sintoma → Diagnóstico → Ação.

Omie HTTP 425 (ban 31min)

• Sintoma — backend logs com error_type=BanError. Requests subsequentes ao Omie falham mesmo após retry.
• Diagnóstico — bucket de abuse detection estourou: 10ª request incorreta (4xx/5xx) no mesmo IP+AppKey+Método em janela curta dispara ban de 31min na Omie.
• Ação — NUNCA retentar antes de 31min (extende o ban). Filtrar Sentry por error_type=BanError pra entender qual call disparou. Verificar se Gap 5 (BanError → 503 com Retry-After header) está implementado no backend; sem isso, Bubble não sabe quando voltar.

Pagar.me HMAC mismatch

• Sintoma — POST /webhooks/pagarme retorna 401 Unauthorized. Pagar.me dashboard mostra entregas falhando.

• Diagnóstico — PAGARME_WEBHOOK_SECRET foi rotated no dashboard Pagar.me mas backend ainda usa o secret antigo. HMAC computa hash diferente → handler rejeita.

• Ação — recuperar secret atual e atualizar env do backend:

  bw get password 'pagarme-webhook-secret-staging'
  export PAGARME_WEBHOOK_SECRET=...
  cd backend && kamal env push && kamal app boot

Backend container restart loop

• Sintoma — https://blu-omie-api.fonsecagabriel.com.br/health/live retorna 502 Bad Gateway. kamal app details mostra container restartando.

• Diagnóstico — duas causas frequentes: (a) Alembic migration falhou no boot, (b) volume /srv/blu-omie-api/data sem permissão de escrita (sqlite não consegue criar/abrir DB).

• Ação — SSH no VPS pra inspecionar:

  ssh root@62.171.145.76
  docker logs <container_id> --tail 100
  # Se erro de permissão no volume:
  chmod 777 /srv/blu-omie-api/data

  Depois redeploy: cd backend && kamal redeploy.