Modulo 1.6 - Integracoes n8n + Supabase

🔁 Substituir HTTP Request no n8n

No n8n, o no Execute Command chama qualquer binario do host. Trocar HTTP Request pela sua CLI centraliza auth, cache e parsing.

Configuracao do node

Node: Execute Command
Command: brasil-api cnpj {{ $json.cnpj }} --fields razao_social,situacao --json
Working Directory: /home/n8n
Continue On Fail: true

O stdout vira $json.stdout. Adicione um node Code com JSON.parse(items[0].json.stdout) para mergulhar nos campos.

✓ Ganhos

✓Cache local entre execucoes do fluxo
✓Auth nao polui credenciais do n8n
✓Mesmo binario funciona no laptop e no servidor

✗ Cuidados

✗n8n self-hosted: binario tem que estar no PATH do container
✗Cache compartilhado precisa de bind mount em ~/.cache
✗Execute Command nao funciona em n8n cloud (so self-host)

📤 Padroes de output: --json vs texto

Uma CLI atende dois consumidores: orquestrador (n8n, scripts) que precisa de JSON; agente que prefere texto curto. Dual output e padrao.

Comparacao

# Default: humano/agente
$ brasil-api cep 01310100
Av. Paulista, Bela Vista, Sao Paulo/SP

# Para n8n / scripts
$ brasil-api cep 01310100 --json
{"cep":"01310-100","logradouro":"Av. Paulista","bairro":"Bela Vista","cidade":"Sao Paulo","uf":"SP"}

# Streaming (uma linha por item)
$ brasil-api bancos --ndjson | head -3
{"code":"001","name":"BANCO DO BRASIL"}
{"code":"033","name":"SANTANDER"}
{"code":"104","name":"CAIXA"}

🔢 Versionar o schema

Use --api-version 1 nos comandos. Quando o output JSON precisar mudar, suba para --api-version 2 e mantenha o 1 funcionando por 6 meses. Fluxos antigos do n8n nao quebram.

🐘 CLI para Supabase com SQLite mirror

CLI faz pull periodico de tabelas do Postgres para SQLite local. Agente consulta milhares de linhas sem bater rate limit nem gastar token.

Exemplo: supabase-pp-cli

# Sync inicial (full)
$ supabase-pp-cli sync clientes --full
Synced 12.483 rows in 4.2s.

# Sync incremental (a cada 5 min via cron)
$ supabase-pp-cli sync clientes
Synced 42 new/updated rows in 0.3s.

# Query local (lida pelo agente)
$ supabase-pp-cli query "SELECT count(*) FROM clientes WHERE plano='premium'"
2.184

⏱️ Sync incremental

Usa updated_at > last_sync para puxar so o que mudou. Configurar coluna obrigatorio:

ALTER TABLE clientes ADD COLUMN updated_at TIMESTAMPTZ DEFAULT now();
CREATE INDEX ON clientes(updated_at);

🔍 Busca semantica local

Crie FTS5 sobre as colunas relevantes no SQLite mirror. O agente pesquisa em texto livre e voce nunca chama o Postgres.

🔑 Auth: env vs printing-press auth

Duas maneiras de fornecer credenciais. Cada cenario tem a sua melhor.

🌳 Env vars

export SUPABASE_URL=https://xxx.supabase.co
export SUPABASE_KEY=ey...
supabase-pp-cli sync clientes

Bom para: n8n self-host (config docker-compose), CI/CD, scripts.

🔐 printing-press auth

printing-press auth --cli supabase
> Supabase URL: https://xxx.supabase.co
> Key: (oculta, salva em keychain)

Bom para: dev local, segurança maior, sem .env espalhado.

💡 Boa pratica

CLI deve checar env primeiro, depois keychain, depois flag --key. Permite override em ambiente especifico sem reconfigurar.

🚦 Rate limit e quotas

CLI nao pula rate limit, mas reduz drasticamente o numero de batidas com cache e batch.

Token bucket local

# Configurar limite no printing-press
$ printing-press config set rate.brasil-api 100/min

# A CLI passa a aguardar quando necessario
$ brasil-api cep 01310100  # request 99
Av. Paulista, Bela Vista, Sao Paulo/SP
$ brasil-api cep 01310200  # request 100, espera 600ms
Rua das Flores, Bela Vista, Sao Paulo/SP

⚠️ Retry com backoff

Em 429/503, a CLI gerada faz retry com exponential backoff (1s, 2s, 4s, 8s). Em n8n, configure "Continue On Fail" + branch de retry como rede de seguranca.

📈 Observabilidade: log NDJSON

Quando o fluxo falha em producao, voce precisa de rastro. A flag --log-json escreve eventos estruturados para auditoria.

Ativar logging

$ brasil-api cep 01310100 --log-json

# escreve em ~/.cache/brasil-api/log.ndjson:
{"ts":"2026-05-13T14:22:01Z","level":"info","cmd":"cep","status":200,"latency_ms":143,"cache":false,"request_id":"r_abc123"}
{"ts":"2026-05-13T14:22:01Z","level":"info","cmd":"cep","status":200,"latency_ms":2,"cache":true,"request_id":"r_abc124"}

📊 Consumir o log

# Ver erros das ultimas 24h
$ cat ~/.cache/brasil-api/log.ndjson | jq 'select(.level=="error")'

# Cache hit rate
$ cat ~/.cache/brasil-api/log.ndjson | jq -s 'map(.cache) | (map(select(.))|length) / length * 100'
73.4

No n8n, dispare um fluxo de alerta quando taxa de erro > 5% nas ultimas 100 chamadas.

💡 Padrao request_id

Cada chamada gera um request_id propagado tambem nos headers HTTP. Quando o servico do alvo logar tambem, voce correlaciona em ambos os lados.

✅ Resumo do Modulo

✓

n8n com Execute Command — sua CLI substitui HTTP Request com cache de bonus.

✓

Dual output — texto humano + --json + --ndjson.

✓

Supabase mirror em SQLite — sync incremental por updated_at.

✓

Auth flexivel — env, keychain, flag — com ordem clara.

✓

--log-json para observabilidade — rastro NDJSON com request_id.

Proximo Modulo:

1.7 — Publicando sua CLI no library oficial

← Modulo anterior Proximo Modulo →