Como Conectar o Google Sheets ao Seu App

Para conectar o Google Sheets ao seu app, ative a API do Google Sheets em um projeto do Google Cloud, crie uma conta de serviço, compartilhe a planilha com o e-mail da conta de serviço e guarde a chave dela como um segredo do lado do servidor. Depois, o seu servidor lê linhas com spreadsheets.values.get e adiciona linhas com spreadsheets.values.append. Se os usuários precisarem conectar as próprias planilhas, use OAuth; e, se a planilha for totalmente pública, uma simples chave de API basta para leitura.

Este guia cobre qual método se encaixa, as chamadas que você precisa, as cotas e as armadilhas, e prompts para um construtor de apps com IA. Os detalhes do Google vêm da documentação para desenvolvedores do Google em setembro de 2026.

Por que conectar uma planilha

Motivos comuns:

• Manter o fluxo de trabalho da equipe. A equipe continua editando uma lista de preços ou uma escala no Sheets; o app mostra os dados.
• Coletar dados onde as pessoas já olham. Novos cadastros, pedidos ou respostas de formulário viram linhas.
• Relatórios. Exportar dados do app para uma planilha, para quem vive em planilhas.
• Um degrau intermediário. Começar pela planilha e depois migrar para um banco de dados de verdade. Veja como transformar uma planilha em app.

Escolha como o seu app faz login no Google

O guia de credenciais do Google descreve três tipos:

Para a maioria dos apps, a conta de serviço é a escolha certa: um conjunto de credenciais, de sua propriedade, com acesso apenas às planilhas que você compartilhar explicitamente com ela.

Passo a passo com uma conta de serviço

1. Crie ou escolha um projeto do Google Cloud e ative a API do Google Sheets.
2. Crie uma conta de serviço e uma chave para ela. A chave é um arquivo JSON; trate-a como uma senha.
3. Compartilhe a planilha com o e-mail da conta de serviço, como Leitor para somente leitura ou Editor para escrever. O guia do Google diz que isso é feito pela tela normal de compartilhamento.
4. Guarde a chave como segredo no seu servidor, por exemplo GOOGLE_SERVICE_ACCOUNT_JSON, mais o ID da planilha (a longa sequência na URL da planilha) como SHEET_ID.
5. Chame a API a partir do servidor com a biblioteca cliente do Google para a sua linguagem.
6. Guarde as leituras em cache se muitos visitantes virem os mesmos dados, para não atingir a cota.

As chamadas que você vai usar

Do guia do Google para ler e escrever valores:

Os intervalos usam a notação A1. O Google observa que um intervalo sem nome de aba, como A1:B2, se aplica à primeira aba, então nomeie a aba explicitamente para evitar surpresas quando alguém reordenar as abas.

RAW vs USER_ENTERED

As escritas precisam de um valueInputOption:

• RAW armazena exatamente o que você envia, como texto. =1+2 é guardado como o texto =1+2.
• USER_ENTERED trata a entrada como se tivesse sido digitada no Sheets: datas viram datas e =1+2 vira uma fórmula.

Se você escrever um texto que os usuários digitaram no seu app, use RAW. Com USER_ENTERED, alguém pode enviar uma fórmula que é executada quando um colega abre a planilha.

Cotas e erros

Em setembro de 2026, a página de limites da API do Sheets do Google lista:

Não há limite diário, desde que você fique dentro dos limites por minuto. Ao exceder, a API retorna 429: Too many requests, e o Google recomenda o backoff exponencial truncado: espere mais a cada tentativa falha, com um atraso aleatório, até um máximo. Uma única requisição que leva mais de 180 segundos expira.

Na prática: não chame a API a cada visualização de página. Guarde os dados da planilha em cache por um minuto ou mais, agrupe as leituras com batchGet e agrupe as escritas quando possível.

Opções e trade-offs

Para qualquer coisa com muitos usuários ou dados sensíveis, um banco de dados é a melhor fonte da verdade. Veja o que é um banco de dados.

Prompts para dar ao seu construtor de apps com IA

Ler uma planilha:

Mostre a aba “Cardápio” da nossa planilha do Google na página do cardápio. Use a API do Google Sheets a partir do servidor, com uma conta de serviço cuja chave JSON está no segredo GOOGLE_SERVICE_ACCOUNT_JSON, e o ID da planilha em SHEET_ID. Leia o intervalo Cardápio!A2:D (nome, descrição, preço, categoria). Guarde o resultado em cache por 5 minutos. Se a API falhar, mostre a última versão em cache. Nunca envie a chave para o navegador.

Escrever linhas:

Quando alguém enviar o formulário de contato, salve no nosso banco de dados e também adicione uma linha à aba “Leads” (data, nome, e-mail, mensagem) usando spreadsheets.values.append com valueInputOption RAW. Se o Google retornar 429, tente de novo com backoff exponencial; se ainda falhar, mantenha o lead no banco de dados e tente depois.

Erros comuns

• Esquecer de compartilhar a planilha com o e-mail da conta de serviço. A API então retorna um erro de permissão, mesmo com a chave correta.
• Chave no frontend ou no repositório. A chave JSON dá acesso a todas as planilhas compartilhadas com ela. Veja como manter as chaves de API seguras.
• Usar USER_ENTERED para a entrada do usuário, o que permite injeção de fórmulas.
• Chamar a API a cada requisição e atingir a cota por minuto no primeiro pico de tráfego.
• Depender da posição das colunas. Alguém insere uma coluna e o app lê os dados errados. Leia a linha de cabeçalho e mapeie pelo nome, ou trave o cabeçalho.
• Compartilhar a planilha mais do que o necessário. “Qualquer pessoa com o link” a torna pública.
• Usar uma planilha como banco de dados multiusuário. Escritas simultâneas e permissões ausentes causam perda ou vazamento de dados.

Checklist

• API do Sheets ativada; conta de serviço criada
• Planilha compartilhada com o e-mail da conta de serviço, com o menor papel necessário
• Chave e ID da planilha guardados como segredos do servidor
• Todas as chamadas feitas a partir do servidor
• Nomes das abas usados nos intervalos
• RAW usado para textos fornecidos pelo usuário
• Leituras em cache; erro 429 tratado com backoff
• O app funciona de forma degradada se o Sheets estiver indisponível
• Definido qual lado é a fonte da verdade

Google Sheets na Mythex

A Mythex tem duas formas diferentes de trabalhar com o Sheets. Os conectores ligam a sua conta do Google à Mythex para que o agente possa usá-la enquanto você constrói, por exemplo lendo uma planilha para montar um painel a partir dela; a documentação diz que a credencial fica com o serviço de conexão da Mythex e nunca vai para o seu código (veja Conectores, e aprove cada permissão que o Google pedir). Para o app publicado ler ou escrever em uma planilha por conta própria, o caminho confiável é o deste guia: uma chave de conta de serviço guardada como segredo do projeto e chamadas à API do Sheets a partir do seu servidor, como em Integrar qualquer API. Se você está superando a planilha, peça ao agente para mover os dados para o banco de dados do projeto e construir um painel em cima deles.

Perguntas