SHEETS_FORMULA - Inserir Fórmulas no Google Sheets

O que é este Node?

O SHEETS_FORMULA é o node responsável por inserir fórmulas do Google Sheets em células, permitindo cálculos automáticos e referências dinâmicas.

Por que este Node existe?

Fórmulas automatizam cálculos e mantêm dados atualizados. O SHEETS_FORMULA existe para:

1. Cálculos Automáticos: Somar, multiplicar, calcular médias
2. Referências Dinâmicas: Buscar dados de outras células/abas
3. Funções Avançadas: VLOOKUP, IF, SUMIF, QUERY
4. Atualização Automática: Recalcular quando dados fonte mudam

Como funciona internamente?

Quando o SHEETS_FORMULA é executado, o sistema:

1. Autentica: Valida tokens OAuth2
2. Prepara fórmula: String começando com "="
3. Executa write: Usa spreadsheets.values.update() com valueInputOption='USER_ENTERED'
4. Google Sheets processa: Interpreta e executa a fórmula
5. Retorna resultado: Confirma inserção

Código interno (usa SHEETS_WRITE com valueInputOption='USER_ENTERED'):

case 'formula':
  const formulaResult = await sheets.spreadsheets.values.update({
    spreadsheetId: data.spreadsheetId,
    range: data.range,
    valueInputOption: 'USER_ENTERED',  // Crucial para interpretar fórmulas
    requestBody: {
      values: [[data.formula]],  // Deve começar com "="
    },
  });

  return {
    success: true,
    updatedCells: formulaResult.data.updatedCells,
  };

Quando você DEVE usar este Node?

Use SHEETS_FORMULA quando precisar cálculos automáticos e referências:

Casos de uso

1. Totais: "=SUM(B2:B100)" para somar vendas
2. Condicionais: "=IF(C2>1000,'Alto','Baixo')" para classificar
3. Busca: "=VLOOKUP(A2,Produtos!A:C,2,FALSE)" para buscar preço
4. Agregação: "=SUMIF(D:D,'Concluído',E:E)" para somar condicionalmente

Quando NÃO usar SHEETS_FORMULA

• Valores fixos: Use NODE SHEETS_WRITE diretamente
• Cálculos complexos externos: Processe e escreva resultado

Parâmetros

Campo	Tipo	Obrigatório	Descrição
operation	string	Sim	Deve ser "formula"
spreadsheetId	string	Sim	ID da planilha
range	string	Sim	Célula onde inserir fórmula
formula	string	Sim	Fórmula começando com "="
accessToken	string	Sim	Token OAuth2
refreshToken	string	Sim	Token OAuth2 refresh

Exemplo 1: Calcular Total de Vendas

Objetivo: Inserir fórmula SUM para totalizar vendas

JSON para Importar

{
  "name": "Inserir Fórmula Total",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Fórmula Total",
        "parameters": {
          "operation": "formula",
          "spreadsheetId": "1Vendas_XYZ",
          "range": "Vendas!E101",
          "formula": "=SUM(E2:E100)",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Fórmula de total inserida"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Fórmula de total inserida

Exemplo 2: VLOOKUP para Buscar Preço

Objetivo: Inserir VLOOKUP para buscar preço de produto

JSON para Importar

{
  "name": "VLOOKUP Automático",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sheets_1",
      "type": "google_sheets",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Fórmula VLOOKUP",
        "parameters": {
          "operation": "formula",
          "spreadsheetId": "1Estoque_XYZ",
          "range": "Pedidos!C2",
          "formula": "=VLOOKUP(B2,Produtos!A:C,3,FALSE)",
          "accessToken": "{{google_access_token}}",
          "refreshToken": "{{google_refresh_token}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "🔍 VLOOKUP configurado para buscar preços"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sheets_1" },
    { "source": "sheets_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🔍 VLOOKUP configurado para buscar preços

Resposta do Node

{
  "success": true,
  "updatedCells": 1
}

Boas Práticas

✅ SIM: - Sempre comece fórmulas com "=" - Use referências absolutas ($A$1) quando necessário - Teste fórmulas manualmente antes de automatizar - Documente fórmulas complexas

❌ NÃO: - Não esqueça o "=" no início - Não use referências circulares - Não crie fórmulas muito complexas (divida em etapas)

Dicas

💡 Dica 1: Fórmulas comuns do Google Sheets: - =SUM(A1:A10) - Soma - =AVERAGE(A1:A10) - Média - =IF(A1>100,"Alto","Baixo") - Condicional - =VLOOKUP(A1,B:D,2,FALSE) - Busca vertical - =SUMIF(A:A,"Vendido",B:B) - Soma condicional

💡 Dica 2: Use valueInputOption='USER_ENTERED' para que o "=" seja interpretado como fórmula, não texto.

💡 Dica 3: Referências: - Relativa: A1 (muda ao copiar) - Absoluta: $A$1 (não muda ao copiar) - Mista: $A1 ou A$1

Próximo Node

→ SHEETS_WRITE - Escrever valores fixos → SHEETS_READ - Ler resultado da fórmula