Como criar uma API simples com Google Apps Script e Google Sheets

Sim: você pode criar uma API simples com Google Apps Script e usar uma planilha do Google como banco de dados leve. O endpoint recebe uma requisição HTTP, lê os dados enviados e grava uma nova linha no Sheets. É uma solução útil para protótipos, formulários internos, pequenos painéis e automações que não justificam um servidor próprio.

O caminho abaixo usa JavaScript, Google Sheets e o recurso de web apps do Apps Script. Não é uma API para substituir um sistema de produção com muitos acessos, mas resolve bem tarefas pequenas quando você quer colocar uma integração no ar sem configurar um backend inteiro.

A ideia é simples: um cliente envia nome, e-mail e mensagem em JSON; o Apps Script valida o pedido e adiciona os valores na planilha. No final, você terá uma URL que pode ser chamada por um formulário, pelo n8n ou pelo comando curl.

O que é uma API feita com Google Apps Script?

Uma API é uma porta de entrada para outro sistema conversar com o seu código. Em vez de alguém abrir a planilha e preencher uma linha, um programa envia uma requisição para uma URL. O Apps Script executa a função correspondente e devolve uma resposta, normalmente em JSON.

Nos web apps do Apps Script, requisições GET chamam a função doGet(e) e requisições POST chamam doPost(e). O objeto e carrega parâmetros da URL e, no POST, o conteúdo enviado no corpo da requisição. A própria documentação do Google explica os web apps do Apps Script e os campos desse evento.

O que você precisa antes de começar

• Uma conta Google com acesso ao Google Sheets e ao Apps Script;
• uma planilha nova, com uma aba chamada Leads;
• na primeira linha, os títulos Data, Nome, E-mail e Mensagem;
• o ID da planilha, que aparece entre /d/ e /edit no endereço do Sheets.

Você pode abrir um projeto independente em script.google.com ou criar o script a partir da planilha em Extensões > Apps Script. O segundo caminho é mais fácil para começar, mas o código ainda pode acessar a planilha explicitamente pelo ID.

Como criar a API com Apps Script e Google Sheets

1. Cole o código no projeto

Apague o conteúdo inicial do editor e cole o exemplo abaixo. Troque COLE_O_ID_DA_PLANILHA pelo ID real do seu arquivo e mantenha o nome da aba igual ao criado no Sheets.

const SHEET_ID = 'COLE_O_ID_DA_PLANILHA';
const SHEET_NAME = 'Leads';

function resposta(dados) {
  return ContentService
    .createTextOutput(JSON.stringify(dados))
    .setMimeType(ContentService.MimeType.JSON);
}

function doGet() {
  return resposta({
    ok: true,
    servico: 'leads-api',
    mensagem: 'API online'
  });
}

function doPost(e) {
  const bloqueio = LockService.getScriptLock();
  bloqueio.waitLock(10000);

  try {
    if (!e || !e.postData || !e.postData.contents) {
      return resposta({ ok: false, erro: 'Corpo JSON ausente' });
    }

    const dados = JSON.parse(e.postData.contents);
    const nome = String(dados.nome || '').trim();
    const email = String(dados.email || '').trim();
    const mensagem = String(dados.mensagem || '').trim();

    if (!nome || !email) {
      return resposta({ ok: false, erro: 'Nome e e-mail são obrigatórios' });
    }

    const aba = SpreadsheetApp
      .openById(SHEET_ID)
      .getSheetByName(SHEET_NAME);

    if (!aba) {
      return resposta({ ok: false, erro: 'Aba não encontrada' });
    }

    aba.appendRow([new Date(), nome, email, mensagem]);
    return resposta({ ok: true, mensagem: 'Lead registrado' });
  } catch (erro) {
    return resposta({ ok: false, erro: 'Não foi possível processar o pedido' });
  } finally {
    bloqueio.releaseLock();
  }
}

O ContentService devolve texto e permite definir o tipo MIME como JSON. Já SpreadsheetApp.openById() abre a planilha e appendRow() acrescenta os dados no fim. A documentação do serviço do Google Sheets explica essa forma de trabalhar com células e intervalos.

2. Por que usar um bloqueio?

O LockService.getScriptLock() evita que duas execuções tentem gravar ao mesmo tempo e acabem disputando a mesma operação. Ele funciona como uma fila curta: uma execução espera a outra liberar o trecho protegido. Isso não transforma a planilha em um banco de dados robusto, mas reduz colisões em uma API pequena.

O limite é importante: o Apps Script tem cotas diárias por usuário e por tipo de conta. A página de cotas dos serviços do Apps Script informa, entre outros limites, chamadas de URL Fetch, tempo total de gatilhos e operações em serviços do Google. Esses números podem mudar, portanto consulte a tabela antes de depender do endpoint em uma operação crítica.

3. Publique como um web app

1. Clique em Implantar > Nova implantação;
2. selecione App da Web como tipo;
3. em “Executar como”, escolha a conta que tem acesso à planilha;
4. em “Quem tem acesso”, escolha a opção compatível com seu cenário, como apenas usuários do domínio ou qualquer pessoa com o link;
5. clique em Implantar, autorize as permissões e copie a URL que termina em /exec.

Para uso real, prefira uma implantação versionada. O Google diferencia a implantação de teste, que acompanha o código atual, da implantação versionada, que mantém uma versão específica disponível para os usuários. A documentação de implantações recomenda não usar a implantação de teste como versão pública.

Como testar a API

Teste GET

Abra a URL /exec no navegador. Se tudo estiver certo, a resposta será parecida com esta:

{"ok":true,"servico":"leads-api","mensagem":"API online"}

Esse teste confirma que a implantação responde, mas não verifica a gravação no Sheets. Para isso, envie um POST.

Teste POST com curl

curl -X POST "SUA_URL_DO_APPS_SCRIPT/exec" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Ana Souza",
    "email": "ana@exemplo.com",
    "mensagem": "Quero receber um orçamento"
  }'

A resposta esperada é {"ok":true,"mensagem":"Lead registrado"}. Depois, abra a planilha e confirme se uma nova linha apareceu com a data, o nome, o e-mail e a mensagem. Se o retorno disser “Aba não encontrada”, confira o nome da guia; se aparecer um erro de permissão, revise a conta escolhida em “Executar como” e faça uma nova autorização.

Como conectar a API a um formulário ou ao n8n

O formulário precisa enviar os mesmos três campos para a URL do web app. Em uma automação, o nó HTTP Request do n8n pode usar o método POST, o cabeçalho Content-Type: application/json e um corpo com nome, email e mensagem. O fluxo fica parecido com Formulário → Apps Script → Google Sheets.

Se você já trabalha com n8n, pode trocar a planilha por um webhook e deixar o n8n cuidar das etapas seguintes. O guia do JSMS sobre webhooks no n8n mostra a lógica de receber uma requisição e encaminhá-la para e-mail, CRM ou outra ferramenta.

Cuidados de segurança antes de divulgar a URL

Uma URL pública não deve ser tratada como segredo. Qualquer pessoa que a descubra pode tentar enviar dados, lotar a planilha ou consumir sua cota. Para um cenário interno, restrinja o acesso aos usuários da organização. Para uma integração externa, valide os campos, limite o que será gravado e considere exigir um token no corpo do pedido usando uma propriedade protegida do script.

Também evite devolver detalhes de exceções ao cliente. O exemplo retorna uma mensagem genérica no bloco catch; os detalhes podem ser investigados no histórico de execuções do Apps Script. Para dados pessoais, defina quem pode abrir a planilha, evite armazenar o que não é necessário e estabeleça um prazo de retenção.

Limitações: quando não usar essa solução

• Muitos acessos simultâneos: a planilha e as cotas do Apps Script podem virar gargalos;
• Autenticação complexa: um web app público não substitui um gateway com controle refinado de usuários, tokens e permissões;
• Dados críticos: pedidos financeiros, informações médicas ou operações que exigem auditoria pedem uma arquitetura própria;
• Consultas avançadas: filtrar, editar e relacionar muitos registros em uma planilha fica frágil mais rápido do que parece.

Para um protótipo, uma ferramenta interna ou um fluxo de baixo volume, a combinação é honesta e eficiente. Para crescer, use a API como prova de conceito e migre a persistência para um banco adequado quando as cotas, a concorrência ou a segurança começarem a incomodar.

Perguntas frequentes

O Google Apps Script pode funcionar como uma API?

Sim. Ao publicar um projeto como web app, as funções doGet(e) e doPost(e) recebem requisições HTTP e podem devolver respostas em texto ou JSON.

Preciso pagar para criar essa API?

Não necessariamente. O Apps Script está disponível para contas Google, mas há cotas e limitações que variam conforme o tipo de conta. Antes de colocá-la em produção, confira os limites atuais na documentação oficial.

Posso usar o Google Sheets como banco de dados?

Para protótipos, controles internos e baixo volume, sim. Ele não é a melhor escolha para alta concorrência, dados sensíveis ou consultas complexas.

Por que a API retorna erro de permissão?

Normalmente porque a implantação não está executando com uma conta que acessa a planilha ou porque a autorização ainda não foi concluída. Revise as configurações da implantação e autorize o projeto novamente.