Pular para conteúdo

Tutorial: Processar Planilhas do Google Sheets

Neste tutorial, você vai criar um sistema de automação para processar dados em planilhas do Google Sheets, validar informações, fazer cálculos e gerar relatórios automaticamente.

O Que Você Vai Construir

Um sistema completo de ETL (Extract, Transform, Load) que:

  1. Lê dados de uma planilha Google Sheets
  2. Valida e limpa os dados
  3. Faz cálculos e transformações
  4. Enriquece dados com APIs externas
  5. Gera relatórios consolidados
  6. Salva resultados em outra aba da planilha
  7. Envia notificação por email com resumo

Tempo estimado: 25 minutos

Pré-requisitos

  • ✅ Conta no Lumina Flow Builder
  • ✅ Conta Google com acesso ao Google Sheets
  • ✅ Tutorial básico completo (Primeiro Flow)
  • ✅ Planilha de exemplo criada

Caso de Uso

Você tem uma planilha com dados de vendas diárias que precisa:

  • Validar dados de entrada
  • Calcular totais e comissões
  • Buscar informações de produtos
  • Gerar relatório consolidado
  • Atualizar planilha automaticamente

Passo 1: Configurar Google Sheets API

1.1. Criar Credenciais

  1. Acesse Google Cloud Console
  2. Crie um novo projeto ou selecione existente
  3. Ative a Google Sheets API
  4. Crie credenciais:
  5. Tipo: Service Account
  6. Nome: "Lumina Flow Builder"
  7. Baixe o arquivo JSON de credenciais
  8. Compartilhe sua planilha com o email da service account

1.2. Preparar Planilha de Exemplo

Crie uma planilha com estas abas:

Aba "Vendas" (dados de entrada):

| Data       | Vendedor | Produto ID | Quantidade | Valor Unit |
|------------|----------|------------|------------|------------|
| 2025-01-10 | João     | PROD001    | 5          | 50.00      |
| 2025-01-10 | Maria    | PROD002    | 3          | 75.00      |
| 2025-01-11 | João     | PROD001    | 2          | 50.00      |

Aba "Relatório" (dados de saída):

| Data       | Total Vendas | Comissão | Top Vendedor |
|------------|--------------|----------|--------------|
| (vazio)    | (vazio)      | (vazio)  | (vazio)      |

Aba "Produtos" (referência):

| ID      | Nome          | Categoria | Estoque |
|---------|---------------|-----------|---------|
| PROD001 | Produto A     | Eletrônico| 100     |
| PROD002 | Produto B     | Livros    | 50      |

Passo 2: Criar o Flow

2.1. Novo Flow

  1. Dashboard → "+ Novo Flow"
  2. Nome: "Processar Vendas - Google Sheets"
  3. Descrição: "ETL automático de dados de vendas"
  4. Tags: "sheets", "etl", "vendas"

2.2. Adicionar Variáveis

Clique em Configurações e adicione:

{
  "spreadsheetId": "1ABC...xyz",
  "serviceAccountKey": {
    "type": "service_account",
    "project_id": "seu-projeto",
    "private_key_id": "...",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "client_email": "lumina@seu-projeto.iam.gserviceaccount.com",
    "client_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token"
  },
  "comissionRate": 0.1,
  "emailRecipient": "gerente@empresa.com"
}

Passo 3: Configurar Trigger

3.1. Schedule Trigger

Vamos executar diariamente:

  1. Adicione "Schedule" trigger
  2. Configure:
  3. Nome: "Executar Diariamente"
  4. Cron Expression: 0 8 * * * (todo dia às 8h)
  5. Timezone: America/Sao_Paulo

3.2. Ou Webhook Trigger

Alternativamente, para execução sob demanda:

  1. Adicione "Webhook" trigger
  2. Configure:
  3. Nome: "Processar Manualmente"
  4. Método: POST

Passo 4: Autenticar com Google

4.1. Obter Access Token

Adicione nó "HTTP Request" chamado "Obter Token Google":

// Method
POST

// URL
{{ $vars.serviceAccountKey.token_uri }}

// Headers
{
  "Content-Type": "application/x-www-form-urlencoded"
}

// Body (form-urlencoded)
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "{{ $vars.jwtToken }}"
}

Nota: Para simplificar, use uma biblioteca JWT ou gere o token previamente.

4.2. Alternativa: Use Nó Nativo

Se disponível, use o nó "Google Sheets" nativo:

  1. Arraste "Google Sheets" para o canvas
  2. Configure:
  3. Action: Read
  4. Credentials: Cole o JSON da service account
  5. Spreadsheet ID: {{ $vars.spreadsheetId }}

Passo 5: Ler Dados da Planilha

5.1. Ler Aba "Vendas"

Adicione nó "HTTP Request" chamado "Ler Vendas":

// Method
GET

// URL
https://sheets.googleapis.com/v4/spreadsheets/{{ $vars.spreadsheetId }}/values/Vendas!A2:E1000

// Headers
{
  "Authorization": "Bearer {{ $nodes['obter-token'].output.data.access_token }}",
  "Content-Type": "application/json"
}

Ou com nó nativo:

// Google Sheets Node
{
  "action": "read",
  "spreadsheetId": "{{ $vars.spreadsheetId }}",
  "range": "Vendas!A2:E1000"
}

5.2. Transformar em Objetos

Adicione "Transform" chamado "Transformar Vendas":

{{
  (() => {
    const rows = $node.output.data.values || [];

    return rows.map(row => ({
      data: row[0],
      vendedor: row[1],
      produtoId: row[2],
      quantidade: parseInt(row[3]) || 0,
      valorUnit: parseFloat(row[4]) || 0,
      total: (parseInt(row[3]) || 0) * (parseFloat(row[4]) || 0)
    }));
  })()
}}

Passo 6: Ler Dados de Produtos

6.1. Ler Aba "Produtos"

Adicione "HTTP Request" chamado "Ler Produtos":

// URL
https://sheets.googleapis.com/v4/spreadsheets/{{ $vars.spreadsheetId }}/values/Produtos!A2:D100

// Headers
{
  "Authorization": "Bearer {{ $nodes['obter-token'].output.data.access_token }}"
}

6.2. Criar Lookup de Produtos

Adicione "Transform" chamado "Criar Lookup Produtos":

{{
  (() => {
    const rows = $node.output.data.values || [];

    return rows.reduce((acc, row) => {
      acc[row[0]] = {
        id: row[0],
        nome: row[1],
        categoria: row[2],
        estoque: parseInt(row[3]) || 0
      };
      return acc;
    }, {});
  })()
}}

Passo 7: Validar e Enriquecer Dados

7.1. Validar Vendas

Adicione "Transform" chamado "Validar e Enriquecer":

{{
  (() => {
    const vendas = $nodes['transformar-vendas'].output;
    const produtos = $nodes['criar-lookup-produtos'].output;
    const errors = [];
    const valid = [];

    vendas.forEach((venda, index) => {
      // Validações
      if (!venda.data || !venda.vendedor || !venda.produtoId) {
        errors.push({
          linha: index + 2,
          erro: 'Dados obrigatórios ausentes',
          venda
        });
        return;
      }

      if (venda.quantidade <= 0) {
        errors.push({
          linha: index + 2,
          erro: 'Quantidade inválida',
          venda
        });
        return;
      }

      const produto = produtos[venda.produtoId];
      if (!produto) {
        errors.push({
          linha: index + 2,
          erro: 'Produto não encontrado',
          venda
        });
        return;
      }

      // Verificar estoque
      if (venda.quantidade > produto.estoque) {
        errors.push({
          linha: index + 2,
          erro: 'Estoque insuficiente',
          venda,
          produto
        });
        return;
      }

      // Enriquecer dados
      valid.push({
        ...venda,
        produto: produto.nome,
        categoria: produto.categoria,
        total: venda.quantidade * venda.valorUnit,
        comissao: venda.quantidade * venda.valorUnit * $vars.comissionRate
      });
    });

    return {
      valid,
      errors,
      validCount: valid.length,
      errorCount: errors.length
    };
  })()
}}

Passo 8: Processar e Calcular

8.1. Calcular Métricas

Adicione "Transform" chamado "Calcular Métricas":

{{
  (() => {
    const vendas = $node.output.valid;

    // Total de vendas
    const totalVendas = vendas.reduce((sum, v) => sum + v.total, 0);

    // Total de comissões
    const totalComissoes = vendas.reduce((sum, v) => sum + v.comissao, 0);

    // Vendas por vendedor
    const vendasPorVendedor = vendas.reduce((acc, v) => {
      acc[v.vendedor] = (acc[v.vendedor] || 0) + v.total;
      return acc;
    }, {});

    // Top vendedor
    const topVendedor = Object.entries(vendasPorVendedor)
      .sort(([,a], [,b]) => b - a)[0];

    // Vendas por categoria
    const vendasPorCategoria = vendas.reduce((acc, v) => {
      acc[v.categoria] = (acc[v.categoria] || 0) + v.total;
      return acc;
    }, {});

    // Ticket médio
    const ticketMedio = totalVendas / vendas.length;

    return {
      data: new Date().toISOString().split('T')[0],
      totalVendas: totalVendas.toFixed(2),
      totalComissoes: totalComissoes.toFixed(2),
      topVendedor: topVendedor[0],
      topVendedorTotal: topVendedor[1].toFixed(2),
      ticketMedio: ticketMedio.toFixed(2),
      quantidadeVendas: vendas.length,
      vendasPorVendedor,
      vendasPorCategoria
    };
  })()
}}

Passo 9: Gerar Relatório

9.1. Formatar Dados para Planilha

Adicione "Transform" chamado "Formatar Relatório":

{{
  (() => {
    const metricas = $node.output;

    // Linha do relatório
    const reportRow = [
      metricas.data,
      metricas.totalVendas,
      metricas.totalComissoes,
      metricas.topVendedor,
      metricas.topVendedorTotal,
      metricas.ticketMedio,
      metricas.quantidadeVendas
    ];

    // Detalhes por vendedor
    const vendedorRows = Object.entries(metricas.vendasPorVendedor)
      .map(([vendedor, total]) => [
        metricas.data,
        vendedor,
        total.toFixed(2),
        (total * $vars.comissionRate).toFixed(2)
      ]);

    return {
      reportRow,
      vendedorRows
    };
  })()
}}

Passo 10: Escrever na Planilha

10.1. Atualizar Aba "Relatório"

Adicione "HTTP Request" chamado "Escrever Relatório":

// Method
POST

// URL
https://sheets.googleapis.com/v4/spreadsheets/{{ $vars.spreadsheetId }}/values/Relatório!A2:append?valueInputOption=RAW

// Headers
{
  "Authorization": "Bearer {{ $nodes['obter-token'].output.data.access_token }}",
  "Content-Type": "application/json"
}

// Body
{
  "values": [
    {{ $node.output.reportRow }}
  ]
}

10.2. Criar Aba de Detalhes

Adicione "HTTP Request" chamado "Escrever Detalhes Vendedor":

// URL
https://sheets.googleapis.com/v4/spreadsheets/{{ $vars.spreadsheetId }}/values/Detalhes!A2:append?valueInputOption=RAW

// Body
{
  "values": {{ $node.output.vendedorRows }}
}

Passo 11: Enviar Notificação

11.1. Preparar Email

Adicione "Transform" chamado "Preparar Email":

{{
  (() => {
    const metricas = $nodes['calcular-metricas'].output;
    const erros = $nodes['validar-e-enriquecer'].output.errors;

    const html = `
      <h2>📊 Relatório Diário de Vendas</h2>
      <p><strong>Data:</strong> ${metricas.data}</p>

      <h3>Resumo</h3>
      <ul>
        <li><strong>Total de Vendas:</strong> R$ ${metricas.totalVendas}</li>
        <li><strong>Total de Comissões:</strong> R$ ${metricas.totalComissoes}</li>
        <li><strong>Quantidade de Vendas:</strong> ${metricas.quantidadeVendas}</li>
        <li><strong>Ticket Médio:</strong> R$ ${metricas.ticketMedio}</li>
      </ul>

      <h3>🏆 Top Vendedor</h3>
      <p><strong>${metricas.topVendedor}</strong> - R$ ${metricas.topVendedorTotal}</p>

      <h3>Vendas por Vendedor</h3>
      <table border="1" cellpadding="5">
        <tr>
          <th>Vendedor</th>
          <th>Total</th>
        </tr>
        ${Object.entries(metricas.vendasPorVendedor)
          .map(([v, t]) => `<tr><td>${v}</td><td>R$ ${t.toFixed(2)}</td></tr>`)
          .join('')}
      </table>

      ${erros.length > 0 ? `
        <h3>⚠️ Erros Encontrados (${erros.length})</h3>
        <ul>
          ${erros.map(e => `<li>Linha ${e.linha}: ${e.erro}</li>`).join('')}
        </ul>
      ` : ''}

      <hr>
      <p><small>Relatório gerado automaticamente pelo Lumina Flow Builder</small></p>
    `;

    return {
      to: $vars.emailRecipient,
      subject: `Relatório de Vendas - ${metricas.data}`,
      html
    };
  })()
}}

11.2. Enviar Email

Adicione "HTTP Request" chamado "Enviar Email":

// Use seu serviço de email (SendGrid, Mailgun, etc)

// Method
POST

// URL
https://api.sendgrid.com/v3/mail/send

// Headers
{
  "Authorization": "Bearer {{ $vars.sendgridApiKey }}",
  "Content-Type": "application/json"
}

// Body
{
  "personalizations": [{
    "to": [{"email": "{{ $node.output.to }}"}]
  }],
  "from": {"email": "noreply@empresa.com"},
  "subject": "{{ $node.output.subject }}",
  "content": [{
    "type": "text/html",
    "value": "{{ $node.output.html }}"
  }]
}

Passo 12: Tratamento de Erros

12.1. Verificar Erros Críticos

Adicione "If/Else" para verificar se há muitos erros:

// Condition
{{ $nodes['validar-e-enriquecer'].output.errorCount > 10 }}

12.2. Enviar Alerta

Se houver muitos erros, envie alerta:

{
  "to": "admin@empresa.com",
  "subject": "⚠️ ALERTA: Muitos erros no processamento de vendas",
  "html": "Foram encontrados {{ $nodes['validar-e-enriquecer'].output.errorCount }} erros. Verifique a planilha urgentemente."
}

Passo 13: Logging

13.1. Adicionar Logs

Adicione "Log" nodes em pontos chave:

// Log: Início
{{
  {
    "event": "processing_started",
    "timestamp": new Date().toISOString()
  }
}}

// Log: Dados Lidos
{{
  {
    "event": "data_loaded",
    "vendasCount": $nodes['transformar-vendas'].output.length,
    "produtosCount": Object.keys($nodes['criar-lookup-produtos'].output).length
  }
}}

// Log: Validação
{{
  {
    "event": "validation_completed",
    "valid": $node.output.validCount,
    "errors": $node.output.errorCount
  }
}}

// Log: Conclusão
{{
  {
    "event": "processing_completed",
    "metrics": $nodes['calcular-metricas'].output
  }
}}

Estrutura Final do Flow

Trigger (Schedule/Webhook)
   ↓
Obter Token Google
   ↓
[Paralelo] → Ler Vendas → Transformar Vendas
   ↓      → Ler Produtos → Criar Lookup
   ↓
Validar e Enriquecer
   ↓
Tem Muitos Erros? → Sim → Enviar Alerta
   ↓ Não
   ↓
Calcular Métricas
   ↓
Formatar Relatório
   ↓
[Paralelo] → Escrever Relatório
   ↓      → Escrever Detalhes
   ↓
Preparar Email
   ↓
Enviar Email
   ↓
Log Conclusão

Passo 14: Testar

14.1. Teste Manual

  1. Clique em "Testar Flow"
  2. Veja os logs em tempo real
  3. Verifique a planilha após execução
  4. Confirme recebimento do email

14.2. Verificar Resultados

Abra a planilha e confira:

  • ✅ Aba "Relatório" atualizada
  • ✅ Aba "Detalhes" com dados por vendedor
  • ✅ Email recebido com resumo

Melhorias Avançadas

1. Adicionar Gráficos

Use a API do Google Sheets para criar gráficos:

{
  "requests": [{
    "addChart": {
      "chart": {
        "spec": {
          "title": "Vendas por Vendedor",
          "basicChart": {
            "chartType": "COLUMN",
            "domains": [...],
            "series": [...]
          }
        }
      }
    }
  }]
}

2. Integrar com BigQuery

Para análises mais complexas:

// HTTP Request to BigQuery API
{
  "query": "SELECT vendedor, SUM(total) FROM vendas GROUP BY vendedor"
}

3. Adicionar Machine Learning

Previsão de vendas com API de ML:

// Usar TensorFlow.js ou API externa
{
  "historicalData": [...],
  "predictDays": 7
}

4. Dashboard em Tempo Real

Integre com Data Studio ou Power BI.

Conceitos Aprendidos

Você aprendeu:

  • ✅ Integrar com Google Sheets API
  • ✅ Autenticar com Service Account
  • ✅ Ler e escrever dados em planilhas
  • ✅ Validar e limpar dados
  • ✅ Fazer cálculos e agregações
  • ✅ Enriquecer dados com lookup
  • ✅ Gerar relatórios automáticos
  • ✅ Enviar notificações por email
  • ✅ Processar dados em paralelo
  • ✅ Implementar error handling robusto

Próximos Passos

  1. Automatizar Mais Processos
  2. Conciliação bancária
  3. Gestão de inventário

  4. Folha de pagamento

  5. Integrar Outras Fontes

  6. APIs de CRM
  7. Bancos de dados SQL

  8. Arquivos CSV/Excel

  9. Criar Dashboards

  10. Google Data Studio
  11. Power BI
  12. Grafana

Recursos Úteis

← WhatsApp Integration | Tutoriais