Como criar uma API com Google Apps Script e Google Sheets

Se você precisa entregar dados de uma planilha para um site, aplicativo ou automação, não precisa começar montando um servidor do zero. O Google Apps Script pode publicar um projeto como uma aplicação web e devolver JSON por uma URL.

Neste guia, vou mostrar o caminho mais simples: criar uma planilha de produtos, ler as linhas com JavaScript e expor o resultado como uma API. Também explico como receber dados por POST, testar o endpoint e evitar o erro clássico de deixar informação particular aberta na internet.

O que é uma API feita com Apps Script?

API é uma porta de comunicação entre sistemas. Em vez de uma pessoa abrir a planilha, outro programa faz uma requisição HTTP e recebe uma resposta estruturada, normalmente em JSON. É o mesmo princípio de um aplicativo consultando um catálogo de produtos ou de um fluxo no n8n buscando uma lista de clientes.

No Apps Script, uma aplicação web precisa ter uma função doGet(e) ou doPost(e). O Google chama a função conforme o método usado na requisição, e o objeto e traz parâmetros da URL ou o corpo enviado no POST. A documentação oficial também informa que o projeto pode ser executado como o proprietário ou como o usuário que acessa o web app — uma escolha que muda as permissões disponíveis.

O retorno pode ser um TextOutput produzido pelo ContentService. Com ele, o script devolve texto, CSV ou JSON sem precisar criar uma interface visual. Para entender a diferença entre consultar uma fonte e disparar uma ação, veja também este guia do JSMS sobre como enviar e-mails automáticos pelo Google Sheets com Apps Script.

Antes de começar

• Uma conta Google;
• Uma planilha com uma aba chamada Produtos;
• Na primeira linha, os nomes das colunas: nome, preco e estoque;
• O ID da planilha, que aparece entre /d/ e /edit no endereço do Google Sheets.

O exemplo abaixo é adequado para catálogo interno, protótipo, painel simples ou automação de baixo volume. Ele não substitui uma API com banco de dados, controle de usuários, logs e proteção contra abuso quando o projeto crescer.

Como criar a API que lê o Google Sheets

1. Abra o editor do Apps Script

Na planilha, abra Extensões > Apps Script. Apague o conteúdo inicial do arquivo e cole este código:

const SHEET_ID = 'COLE_AQUI_O_ID_DA_PLANILHA';
const TAB_NAME = 'Produtos';
const TOKEN = 'troque-por-uma-chave-dificil-de-adivinhar';

function doGet(e) {
  const token = e && e.parameter ? e.parameter.token : '';

  if (token !== TOKEN) {
    return json_({ ok: false, error: 'unauthorized' });
  }

  const sheet = SpreadsheetApp
    .openById(SHEET_ID)
    .getSheetByName(TAB_NAME);

  if (!sheet) {
    return json_({ ok: false, error: 'Aba não encontrada' });
  }

  const values = sheet.getDataRange().getDisplayValues();

  if (values.length === 0) {
    return json_({ ok: true, data: [] });
  }

  const headers = values.shift();
  const data = values
    .filter(row => row.some(cell => cell !== ''))
    .map(row => Object.fromEntries(
      headers.map((header, index) => [
        header || `coluna_${index + 1}`,
        row[index] || ''
      ])
    ));

  return json_({ ok: true, data });
}

function json_(payload) {
  return ContentService
    .createTextOutput(JSON.stringify(payload))
    .setMimeType(ContentService.MimeType.JSON);
}

Troque o ID e o valor de TOKEN. O código usa a primeira linha como cabeçalho e transforma cada linha seguinte em um objeto. Assim, uma tabela como nome | preco | estoque vira uma lista de objetos com essas mesmas chaves.

2. Salve e autorize o projeto

Clique em Salvar e execute uma função pelo editor se o Google pedir autorização. Como o script abre uma planilha, a conta responsável pela execução precisará ter acesso a ela. Se você optar por executar como proprietário, os visitantes não precisam receber acesso direto à planilha — mas isso torna ainda mais importante validar os dados que serão expostos.

3. Publique como aplicação web

No canto superior direito, abra Implantar > Nova implantação, selecione o tipo de aplicação web e conclua a configuração. O Apps Script gera uma URL de implantação com final /exec. É essa URL que você usará no site, no n8n ou no comando de teste.

A URL de teste com final /dev é diferente: a documentação informa que ela só pode ser acessada por pessoas com permissão de edição no projeto e sempre usa o código salvo mais recentemente. Portanto, não coloque /dev em uma integração que precisa funcionar para clientes.

Como testar o endpoint JSON

Substitua SUA_URL pela URL de implantação e rode:

curl "SUA_URL/exec?token=troque-por-uma-chave-dificil-de-adivinhar"

Se tudo estiver certo, o retorno será parecido com este:

{
  "ok": true,
  "data": [
    {
      "nome": "Mouse sem fio",
      "preco": "89,90",
      "estoque": "12"
    }
  ]
}

O valor de preco aparece como texto porque o exemplo usa getDisplayValues(): isso preserva o formato que você vê na planilha. Se o consumidor precisar fazer cálculos, normalize o número no código ou envie os valores brutos com getValues() e trate datas e moedas no sistema que recebe a resposta.

Como receber dados com doPost

Para gravar um formulário ou webhook em uma nova linha, acrescente uma função doPost. Neste exemplo, a aba tem as colunas data, nome, email e mensagem:

function doPost(e) {
  const token = e && e.parameter ? e.parameter.token : '';

  if (token !== TOKEN) {
    return json_({ ok: false, error: 'unauthorized' });
  }

  let body;
  try {
    body = JSON.parse(e.postData.contents || '{}');
  } catch (error) {
    return json_({ ok: false, error: 'JSON inválido' });
  }

  if (!body.nome || !body.email) {
    return json_({ ok: false, error: 'nome e email são obrigatórios' });
  }

  const sheet = SpreadsheetApp
    .openById(SHEET_ID)
    .getSheetByName('Leads');

  sheet.appendRow([
    new Date(),
    body.nome,
    body.email,
    body.mensagem || ''
  ]);

  return json_({ ok: true, message: 'Registro salvo' });
}

Faça o teste com:

curl -X POST "SUA_URL/exec?token=troque-por-uma-chave-dificil-de-adivinhar" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Ana","email":"ana@exemplo.com","mensagem":"Quero saber o prazo"}'

O mesmo endpoint pode ter doGet e doPost; o método HTTP escolhido determina qual função é chamada. Em um fluxo no n8n ou no Make, configure a URL da implantação, envie o cabeçalho de conteúdo como JSON e trate a resposta ok: false como erro.

Limitações e cuidados de segurança

Não confunda uma URL com autenticação

O token do exemplo evita chamadas acidentais, mas não é uma solução completa de autenticação. Ele aparece na URL, pode parar em logs e pode ser copiado por quem tiver acesso ao fluxo. Para dados pessoais, pedidos, pagamentos ou informações internas, prefira autenticação adequada, validação no servidor, controle de permissões ou uma API própria.

Não publique uma planilha particular sem revisar o código

Quem acessar um web app executado como proprietário pode receber dados que normalmente não estariam públicos na planilha. Retorne somente as colunas necessárias, filtre registros e evite usar getDataRange() em uma tabela enorme sem paginação ou limite.

Considere as cotas

Apps Script tem cotas e limites de execução que variam conforme o serviço e o tipo de conta. Uma planilha funciona bem como camada de dados para protótipos e pequenos fluxos, mas pode virar gargalo quando muitos usuários fazem requisições ao mesmo tempo. Consulte a página de cotas do Google antes de transformar este exemplo em um backend de alto tráfego.

Quando usar essa solução?

Use Apps Script + Sheets quando…	Procure outra solução quando…
Você precisa de um catálogo, formulário ou webhook simples.	Há dados sensíveis ou exigência de autenticação robusta.
A equipe já trabalha no Google Sheets e quer editar dados sem painel novo.	Existem muitas escritas simultâneas e regras complexas.
O volume é pequeno e a prioridade é colocar um protótipo no ar.	Você precisa de alta disponibilidade, métricas e escalabilidade previsível.

O ganho está na velocidade: uma planilha vira uma fonte de dados acessível por HTTP em poucos minutos. O limite também é claro: isso continua sendo uma automação apoiada em uma planilha, não um banco de dados profissional disfarçado de API.

Perguntas frequentes

Preciso contratar hospedagem para criar a API?

Não para este exemplo. O código é executado pela infraestrutura do Apps Script, e o Google fornece a URL da aplicação web. Você ainda depende das permissões, cotas e condições da conta Google.

Posso usar a API em um site público?

Pode, desde que a resposta contenha apenas dados que realmente podem ser públicos. Para informações privadas, não deixe o endpoint aberto e não trate um token fixo na URL como autenticação suficiente.

Qual é a diferença entre as URLs /dev e /exec?

/dev é voltada a testes e exige acesso de edição ao projeto. /exec é a implantação usada por consumidores do web app e só muda quando você cria uma nova versão ou atualiza a implantação.

O Apps Script substitui um banco de dados?

Não em cenários de produção mais exigentes. Ele é uma ponte prática para pequenos projetos, mas banco de dados, API própria ou serviço especializado oferecem controles melhores para autenticação, concorrência, auditoria e escala.