Automatizar planilhas com Claude Code: CSV, Google Sheets API e Apps Script

Automação de planilhas parece uma tarefa simples, mas normalmente toca vendas, formulários de contato, custos de anúncios, faturas e métricas de conteúdo. Quando uma regra de importação falha, o problema não é apenas uma linha faltando: o time pode tomar decisões com receita, prioridade ou custo errado.

Claude Code ajuda porque trabalha dentro do repositório. Ele pode criar um resumo CSV, um script para adicionar linhas com Google Sheets API, uma automação com Apps Script e uma nota de verificação com arquivos alterados, comandos executados e riscos restantes. Esse registro é o que transforma um script rápido em um processo revisável.

Este guia começa com CSV local, depois grava leads no Google Sheets e por fim classifica consultas com Apps Script. Para a rotina de trabalho, leia também as dicas de produtividade com Claude Code e o workflow de verificação. Referências oficiais: Claude Code docs, Claude Code CLI usage, Google Sheets API Node.js quickstart, Apps Script Sheets guide e SheetJS docs.

Defina a fronteira dos dados

Antes de escolher biblioteca, decida qual tabela é a fonte de verdade. Se o mesmo valor pode ser editado em CSV, Google Sheets, CRM e sistema financeiro, a automação apenas acelera a confusão. Separe entrada bruta, camada limpa e relatório.

Camada	Papel	Exemplo	O que pedir ao Claude Code
Raw	Dados de entrada sem edição manual	formulários, CSV de pagamentos, export de anúncios	importação, validação, linhas com erro
Clean	Dados tipados e normalizados	datas, valores, status	normalização, deduplicação, colunas obrigatórias
Report	Saída para humanos	receita mensal, prioridade de leads, KPI	resumos, CSV para gráficos, alertas

O erro comum é escrever direto na aba Report. Essa aba costuma ter cores, fórmulas, notas e layout humano. Máquinas preferem cabeçalhos estáveis e linhas append-only. Escreva em Raw ou Clean e gere o Report com fórmulas, tabela dinâmica, Looker Studio ou outro script.

Exemplo 1: resumir vendas CSV por mês

Comece sem credenciais do Google. Assim Claude Code cria uma base reproduzível e qualquer pessoa pode validar localmente.

Crie data/sales.csv.

date,channel,product,amount,status
2026-05-01,organic,Claude Code Cheatsheet,0,won
2026-05-02,gumroad,Prompt Template Pack,2980,won
2026-05-08,consultation,Team Workshop,120000,won
2026-05-11,gumroad,Prompt Template Pack,2980,refunded
2026-06-01,organic,Claude Code Cheatsheet,0,won
2026-06-02,consultation,Implementation Review,80000,won

Salve scripts/summarize-sales.mjs.

import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";

const inputPath = process.argv[2] ?? "data/sales.csv";
const outputPath = process.argv[3] ?? "out/monthly-summary.csv";

function parseCsvLine(line) {
  const cells = [];
  let current = "";
  let inQuotes = false;

  for (let index = 0; index < line.length; index += 1) {
    const char = line[index];
    const next = line[index + 1];

    if (char === '"' && inQuotes && next === '"') {
      current += '"';
      index += 1;
      continue;
    }

    if (char === '"') {
      inQuotes = !inQuotes;
      continue;
    }

    if (char === "," && !inQuotes) {
      cells.push(current.trim());
      current = "";
      continue;
    }

    current += char;
  }

  cells.push(current.trim());
  return cells;
}

function parseCsv(source) {
  const lines = source.trim().split(/\r?\n/).filter(Boolean);
  const headers = parseCsvLine(lines[0]);

  return lines.slice(1).map((line) => {
    const cells = parseCsvLine(line);
    return Object.fromEntries(headers.map((header, index) => [header, cells[index] ?? ""]));
  });
}

function toMonth(dateValue) {
  const date = new Date(`${dateValue}T00:00:00Z`);
  if (Number.isNaN(date.getTime())) {
    throw new Error(`Invalid date: ${dateValue}`);
  }
  return dateValue.slice(0, 7);
}

const rows = parseCsv(await readFile(inputPath, "utf8"));
const summary = new Map();

for (const row of rows) {
  if (row.status !== "won") continue;

  const amount = Number(row.amount);
  if (!Number.isFinite(amount)) {
    throw new Error(`Invalid amount: ${JSON.stringify(row)}`);
  }

  const key = `${toMonth(row.date)},${row.channel}`;
  const current = summary.get(key) ?? { month: toMonth(row.date), channel: row.channel, deals: 0, revenue: 0 };
  current.deals += 1;
  current.revenue += amount;
  summary.set(key, current);
}

const output = [
  "month,channel,deals,revenue",
  ...[...summary.values()]
    .sort((a, b) => `${a.month}:${a.channel}`.localeCompare(`${b.month}:${b.channel}`))
    .map((row) => `${row.month},${row.channel},${row.deals},${row.revenue}`),
].join("\n");

await mkdir(path.dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${output}\n`, "utf8");

console.log(`Wrote ${outputPath} (${summary.size} groups)`);

Execute.

mkdir -p data out scripts
node scripts/summarize-sales.mjs data/sales.csv out/monthly-summary.csv
cat out/monthly-summary.csv

O ponto importante é falhar de modo visível. Valor vazio, data inválida ou status inesperado não devem virar zero em silêncio. Depois peça ao Claude Code números de linha, arquivo de rejeitados e testes para reembolsos.

Exemplo 2: adicionar leads com Google Sheets API

Em equipes, conta de serviço costuma ser mais auditável que OAuth pessoal. Ative Sheets API no Google Cloud, crie a chave JSON, compartilhe a planilha com o email da conta de serviço e crie uma aba Raw com createdAt,source,subject,amount,status.

npm install googleapis
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/service-account.json"
export SHEET_ID="your-google-sheet-id"

Crie scripts/append-lead-to-sheet.mjs.

import { google } from "googleapis";

const { GOOGLE_APPLICATION_CREDENTIALS, SHEET_ID } = process.env;

if (!GOOGLE_APPLICATION_CREDENTIALS) {
  throw new Error("GOOGLE_APPLICATION_CREDENTIALS is required");
}

if (!SHEET_ID) {
  throw new Error("SHEET_ID is required");
}

const auth = new google.auth.GoogleAuth({
  keyFile: GOOGLE_APPLICATION_CREDENTIALS,
  scopes: ["https://www.googleapis.com/auth/spreadsheets"],
});

const sheets = google.sheets({ version: "v4", auth });

const source = process.argv[2] ?? "web";
const subject = process.argv[3] ?? "Claude Code consultation";
const amount = Number(process.argv[4] ?? 0);

if (!Number.isFinite(amount)) {
  throw new Error(`Invalid amount: ${process.argv[4]}`);
}

await sheets.spreadsheets.values.append({
  spreadsheetId: SHEET_ID,
  range: "Raw!A:E",
  valueInputOption: "USER_ENTERED",
  insertDataOption: "INSERT_ROWS",
  requestBody: {
    values: [[new Date().toISOString(), source, subject, amount, "new"]],
  },
});

console.log("Appended lead row");

Exemplo de execução:

node scripts/append-lead-to-sheet.mjs newsletter "Spreadsheet automation review" 50000

Ao pedir alterações ao Claude Code, preserve nomes de variáveis, intervalo, ordem das colunas e regra de não versionar credenciais. service-account.json não deve entrar em Git, issues, documentação ou prompts.

Exemplo 3: classificar vendas e consultas com Apps Script

Apps Script é útil quando o fluxo já está no Google Workspace. Ele reage a formulários, escreve em Sheets e envia email sem servidor próprio. Mesmo assim, há quotas, triggers e permissões. Antes de alto volume, veja Apps Script quotas.

Cole no editor Apps Script e configure um trigger instalável de envio de formulário para onFormSubmit.

const SETTINGS = {
  sheetName: "Leads",
  notifyTo: "sales@example.com",
  minAmountForHighPriority: 100000,
};

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("Lead Ops")
    .addItem("Rebuild lead status", "rebuildLeadStatus")
    .addToUi();
}

function onFormSubmit(event) {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName(SETTINGS.sheetName) || spreadsheet.insertSheet(SETTINGS.sheetName);
  ensureHeader_(sheet);

  const values = event && event.namedValues ? event.namedValues : {};
  const company = first_(values, "Company");
  const email = first_(values, "Email");
  const plan = first_(values, "Plan");
  const budget = Number(first_(values, "Budget") || 0);
  const priority = classifyLead_(plan, budget);

  sheet.appendRow([new Date(), company, email, plan, budget, priority, "new"]);

  if (priority === "high") {
    MailApp.sendEmail({
      to: SETTINGS.notifyTo,
      subject: `High priority lead: ${company}`,
      body: `Company: ${company}\nEmail: ${email}\nPlan: ${plan}\nBudget: ${budget}`,
    });
  }
}

function rebuildLeadStatus() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(SETTINGS.sheetName);
  if (!sheet) throw new Error(`Sheet not found: ${SETTINGS.sheetName}`);
  ensureHeader_(sheet);

  const values = sheet.getDataRange().getValues();
  for (let rowIndex = 1; rowIndex < values.length; rowIndex += 1) {
    const row = values[rowIndex];
    const plan = String(row[3] || "");
    const budget = Number(row[4] || 0);
    const priority = classifyLead_(plan, budget);
    sheet.getRange(rowIndex + 1, 6).setValue(priority);
  }
}

function ensureHeader_(sheet) {
  const header = ["createdAt", "company", "email", "plan", "budget", "priority", "status"];
  const current = sheet.getRange(1, 1, 1, header.length).getValues()[0];
  if (current.join("") === "") {
    sheet.getRange(1, 1, 1, header.length).setValues([header]);
    sheet.setFrozenRows(1);
  }
}

function classifyLead_(plan, budget) {
  const normalizedPlan = String(plan).toLowerCase();
  if (budget >= SETTINGS.minAmountForHighPriority || normalizedPlan.includes("team")) {
    return "high";
  }
  if (budget >= 30000) {
    return "medium";
  }
  return "low";
}

function first_(namedValues, key) {
  const value = namedValues[key];
  return Array.isArray(value) ? value[0] || "" : "";
}

Adapte os nomes dos campos ao formulário real. Se o formulário estiver em português, troque Company, Plan e Budget pelos rótulos exatos e peça que Claude Code não registre dados pessoais em logs.

Template para Claude Code

Uma boa solicitação limita escopo e verificação.

You are working on spreadsheet automation for this repository.

Goal:
- Import sales CSV rows from data/sales.csv.
- Write a monthly summary to out/monthly-summary.csv.
- Add a Google Sheets append script for the Raw tab.

Scope:
- You may edit scripts/summarize-sales.mjs and scripts/append-lead-to-sheet.mjs.
- You may add small tests or sample CSV files if needed.
- Do not edit content files, product links, analytics, or deployment settings.

Rules:
- Do not commit credentials.
- Use environment variables for SHEET_ID and GOOGLE_APPLICATION_CREDENTIALS.
- Fail loudly on invalid dates, invalid amounts, and missing required columns.
- Keep the code copy-paste runnable with Node.js 20 or later.

Verification:
- Run node --check on every script you edit.
- Run the CSV summary against data/sales.csv.
- For Google Sheets API, verify syntax locally and list the manual credential checks.
- Return changed files, commands run, output summary, and remaining risks.

Comandos de verificação:

node --check scripts/summarize-sales.mjs
node scripts/summarize-sales.mjs data/sales.csv out/monthly-summary.csv
node --check scripts/append-lead-to-sheet.mjs
git diff -- scripts/summarize-sales.mjs scripts/append-lead-to-sheet.mjs

Em equipe, mova essa parte para CLAUDE.md e combine com o guia de permissões Claude Code.

Casos de uso reais

O primeiro caso é relatório mensal de receita. Junte exports Gumroad, Stripe, faturas manuais e cadastros gratuitos. Reembolsos ficam fora da receita, leads gratuitos contam como volume e nomes de produto precisam ser normalizados.

O segundo caso é triagem de consultas. Orçamento, tamanho do time, plano escolhido e domínio de cliente existente podem virar regras. Elas precisam ser explicáveis: “orçamento acima de 100000 ienes ou plano team” é revisável; “parece promissor” não é.

O terceiro caso é KPI de artigos e anúncios. Uma planilha pode guardar slug, data de publicação, cliques de busca, cliques de CTA, cliques de produto e início de formulário. Para nomes de evento, conecte com o guia de analytics com Claude Code.

O quarto caso é conferência antes da fatura. Compare logs de entrega com CSV de faturas e escreva apenas divergências em uma aba de revisão. Não comece automatizando envio de fatura.

Armadilhas comuns

A primeira armadilha são cabeçalhos instáveis. Se Amount, amount e Receita aparecem juntos, o script pode terminar sem erro e ignorar linhas. Peça validação de colunas obrigatórias.

A segunda é tratar Sheets como banco de dados. Sheets é ótimo para colaboração e revisão, mas não para transações, locks, permissões canônicas ou escrita em massa. Pagamentos e acessos devem ficar no banco da aplicação.

A terceira é vazar credenciais. JSON de conta de serviço não deve entrar em prompts, issues, docs ou commits. Diga a Claude Code para não ler, imprimir ou commitar segredos.

A quarta é esquecer triggers do Apps Script. Colar código não basta. Confira trigger instalável, usuário de execução, primeira autorização, quota de email e alerta de erro.

A quinta é olhar só o total final. Todo relatório deve mostrar linhas lidas, linhas excluídas, erros e horário da última atualização.

CTA: transformar scripts em operação

Automação de planilhas fica confiável quando prompts, permissões e verificação são repetíveis. Comece com a cola gratuita de Claude Code para comandos e hábitos de revisão. Para prompts reutilizáveis e modelos CLAUDE.md, veja os produtos ClaudeCodeLab.

Se o time usa planilhas para vendas, leads, anúncios ou faturas, defina fronteira de credenciais e aprovação humana antes de adicionar mais scripts. Para desenhar isso com apoio, use treinamento e consultoria Claude Code.

Resultado ao testar

No fluxo de Masa, o maior ganho veio antes da API do Sheets: fixar cabeçalhos CSV, regras de exclusão e comportamento de erro. Apps Script foi bom para classificar leads, mas regras vagas de notificação geraram emails demais. A abordagem mais estável foi separar Raw, Clean e Report e pedir ao Claude Code pequenas implementações verificadas.