APIs, Integrações,
Segurança e Infraestrutura

O sistema utiliza exclusivamente a API REST gerada automaticamente pelo PostgREST do Supabase, sem APIs customizadas próprias. Toda a comunicação segue o padrão HTTPS + JSON com autenticação via JWT Bearer token no header Authorization.

4.1 PostgREST — Endpoints do Módulo Licenciamento

Base URL

Base URL:  https://geojgcncmtbjebftosor.supabase.co/rest/v1

Headers obrigatórios:
  apikey:        {SUPABASE_ANON_KEY}
  Authorization: Bearer {JWT_TOKEN}
  Content-Type:  application/json
  Prefer:        return=representation  // para receber o registro inserido/atualizado

// Buscar todos os leads ordenados por data
GET /lic_leads?order=created_at.desc

// Filtrar só convertidos
GET /lic_leads?status=eq.Convertido

// Buscar por token do portal
GET /lic_leads?form_token=eq.TOKEN&limit=1

// Selecionar campos específicos
GET /lic_leads?select=id,razao_social,status,uf,area_total_m2

[
  {
    "id": 1,
    "razao_social": "Logística ABC Ltda.",
    "status": "Convertido",
    "uf": "SP",
    "area_total_m2": 12000,
    "created_at": "2026-03-15T10:30:00Z"
  }
]

{
  "razao_social": "Logística ABC Ltda.",
  "status": "Ativo",
  "etapa": "Prospecção",
  "criado_por": "gppereira@vendemmia.com.br",
  "created_at": "2026-05-30T14:00:00Z"
}

// Retorna o registro criado com id gerado
[{ "id": 42, "razao_social": "Logística ABC Ltda.", ... }]

{
  "status": "Convertido",
  "updated_at": "2026-05-30T14:30:00Z"
}

Endpoints das demais tabelas do módulo

4.2 Supabase Auth API

Estrutura do JWT Token

// Header
{ "alg": "HS256", "typ": "JWT" }

// Payload (claims relevantes)
{
  "iss": "supabase",
  "ref": "geojgcncmtbjebftosor",
  "role": "authenticated",         // ou "anon" para portal público
  "email": "gppereira@vendemmia.com.br",
  "sub": "uuid-do-usuario",
  "iat": 1748610000,
  "exp": 1748613600              // expira em 1h; SDK faz refresh automático
}

4.3 Supabase Storage API

Padrão de upload com tratamento de erros

async function uploadAnexo(file, leadId, tipo) {
  const safe = file.name.replace(/[^a-zA-Z0-9._-]/g, '_');
  const path = `leads/${leadId}/${tipo}/${Date.now()}_${safe}`;

  const { error: upErr } = await supabaseClient.storage
    .from('lic-anexos')
    .upload(path, file, {
      cacheControl: '3600',
      upsert: false  // nunca sobrescrever — sempre gerar novo path
    });

  if (upErr) throw upErr;  // 409 = path já existe, 413 = arquivo muito grande

  const { data: urlData } = supabaseClient.storage
    .from('lic-anexos')
    .getPublicUrl(path);  // operação local — URL determinística

  return { path, url: urlData.publicUrl };
}

4.4 APIs Externas

BrasilAPI — Response da geocodificação por CEP

// GET https://brasilapi.com.br/api/cep/v2/01310100
{
  "cep": "01310-100",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Bela Vista",
  "street": "Avenida Paulista",
  "location": {
    "type": "Point",
    "coordinates": {
      "longitude": "-46.6526056",
      "latitude": "-23.5640265"
    }
  }
}

4.5 Padrão de Tratamento de Erros

// Padrão de chamada com tratamento completo
async function carregarLicLeads() {
  try {
    const { data, error } = await supabaseClient
      .from('lic_leads')
      .select('*')
      .order('created_at', { ascending: false });

    if (error) throw error;   // erro da API → capturado pelo catch

    baseLicLeads = data || [];

  } catch (e) {
    // showToast = função global de notificação
    showToast('Erro ao carregar leads: ' + (e.message || e), 'error');
    baseLicLeads = [];  // estado seguro mesmo com erro
  }
}

// Objeto de erro do Supabase
{
  message: "JWT expired",       // mensagem legível
  code:    "PGRST301",        // código PostgREST
  hint:    "...",             // dica de resolução
  details: "..."              // detalhes técnicos
}

5.1 JWT e Gestão de Sessão

// Recuperação de sessão existente (no carregamento da página)
const { data } = await supabaseClient.auth.getSession();
if (data?.session) {
  EMAIL_USUARIO_LOGADO = data.session.user.email.toLowerCase();
  await carregarPerfil(data.session.user.email);
  iniciarSistema();
}

5.2 Controle de Acesso ao Módulo Licenciamento

// Camada 1: Botão oculto no HTML
const LICENCIAMENTO_WHITELIST = [
  'gppereira@vendemmia.com.br',
  'jprado@vendemmia.com.br'
];

// Em aplicarPermissoes() — chamada após login
mostrar('nav-licenciamento', LICENCIAMENTO_WHITELIST
  .includes(EMAIL_USUARIO_LOGADO));

// Camada 2: Guard na função navegar()
function navegar(pagina) {
  if (pagina === 'licenciamento' &&
      !LICENCIAMENTO_WHITELIST.includes(EMAIL_USUARIO_LOGADO)) {
    return;  // bloqueia mesmo se URL for manipulada
  }
  // ...
}

5.3 Row Level Security — Arquitetura de Políticas

Implementação futura de RLS granular

-- Política avançada para lic_leads (versão futura)
CREATE POLICY "lic_leads_whitelist" ON lic_leads
  FOR ALL
  TO authenticated
  USING (
    auth.email() IN (
      SELECT email FROM lic_permissoes WHERE ativo = true
    )
  )
  WITH CHECK (
    auth.email() IN (
      SELECT email FROM lic_permissoes WHERE ativo = true
    )
  );

-- Política específica para portal público (anon com token válido)
CREATE POLICY "lic_leads_portal_anon" ON lic_leads
  FOR SELECT
  TO anon
  USING (form_token IS NOT NULL);

CREATE POLICY "lic_leads_portal_update" ON lic_leads
  FOR UPDATE
  TO anon
  USING (form_token IS NOT NULL)
  WITH CHECK (form_token IS NOT NULL);

5.4 Segurança de Storage e Uploads

5.5 LGPD e Privacidade de Dados

5.6 Análise de Vulnerabilidades

5.7 Logs e Auditoria

6.1 Hosting e CDN

Configuração de DNS e domínio

# DNS Records (Registro.br)
CNAME  pipelinevendemmia.com.br  →  gueilee.github.io
A      pipelinevendemmia.com.br  →  185.199.108.153  (GitHub Pages IPs)
A      pipelinevendemmia.com.br  →  185.199.109.153
A      pipelinevendemmia.com.br  →  185.199.110.153
A      pipelinevendemmia.com.br  →  185.199.111.153

# Arquivo CNAME no repositório (raiz)
pipelinevendemmia.com.br

6.2 CI/CD Pipeline

O pipeline de CI/CD é extremamente simples: qualquer push para o branch main dispara o deploy automático via GitHub Actions, sem testes automatizados no momento.

# .github/workflows/pages.yml (implícito — GitHub Pages automático)

Trigger:  git push origin main
Build:    Nenhum (arquivos estáticos — sem bundler)
Test:     Nenhum (débito técnico — ver Fase 3)
Deploy:   GitHub Pages atualiza em 30-60 segundos
Rollback: git revert HEAD + push (ou revert via GitHub UI)

# Fluxo de deploy
Developer → git add + git commit → git push origin main
         → GitHub detecta push no main
         → GitHub Actions: Pages build job (~30s)
         → Akamai CDN invalida cache (~60s propagação global)
         → pipelinevendemmia.com.br atualizado

Branches e estratégia de versionamento

6.3 Ambientes

Estratégia de ambiente recomendada (evolução)

// Separação de ambientes via variável de configuração
const ENV = {
  production: {
    supabaseUrl: "https://geojgcncmtbjebftosor.supabase.co",
    supabaseKey: "eyJ..."  // anon key PRD
  },
  staging: {
    supabaseUrl: "https://STAGING_PROJECT.supabase.co",
    supabaseKey: "eyJ..."  // anon key HML
  }
};

// Detectar ambiente via hostname
const isProd = location.hostname === 'pipelinevendemmia.com.br';
const config = isProd ? ENV.production : ENV.staging;

6.4 Monitoramento e Observabilidade

6.5 Backup e Disaster Recovery

Procedimento de Disaster Recovery

# Cenário 1: Banco de dados corrompido / dado excluído incorretamente
1. Acessar Supabase Dashboard → Settings → Backups
2. Selecionar backup do dia anterior (ou PITR para ponto específico)
3. Clicar "Restore" → confirmar
4. Aguardar restauração (~15-30 minutos)
5. Verificar integridade dos dados críticos
# RTO: ~30 min | RPO: até 24h de dados

# Cenário 2: Deploy com bug crítico em produção
1. git log --oneline -5  # identificar último commit bom
2. git revert HEAD       # ou revert de múltiplos commits
3. git push origin main  # deploy automático do revert
4. GitHub Pages atualiza em ~60 segundos
# RTO: ~2 min | RPO: 0 (dado não é afetado)

# Cenário 3: Supabase indisponível
1. Frontend carrega normalmente (estático no CDN)
2. Login falha — usuários não conseguem autenticar
3. Dados não carregam — sistema operacionalmente inativo
4. Aguardar recovery do Supabase (SLA 99,9%)
# RTO: depende do Supabase | RPO: 0 (sem escrita durante outage)