# Como consumir API de CPF em Google Apps Script para automacoes no Google Sheets

> Aprenda a criar funções personalizadas no Google Sheets que consultam CPF via API usando Google Apps Script com menus e validação em lote.

**Publicado:** 28/09/2026
**Autor:** Lucas Vieira
**URL:** https://www.cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets

---


Para consumir a API de CPF no Google Apps Script, use `UrlFetchApp.fetch` com o endpoint `https://api.cpfhub.io/cpf/{CPF}` e o header `x-api-key` configurado via `PropertiesService`. A resposta chega em ~900ms e pode ser usada diretamente em fórmulas personalizadas como `=CONSULTAR_CPF_NOME(A2)` ou em menus de validação em lote. A documentação completa do Google Apps Script está disponível em [developers.google.com/apps-script](https://developers.google.com/apps-script).

Google Sheets é uma das ferramentas mais utilizadas no ambiente corporativo brasileiro. Equipes de RH, financeiro, compliance e operações frequentemente gerenciam listas de CPFs em planilhas — para validação de cadastros, conferência de dados de funcionários ou verificação de clientes. O Google Apps Script permite estender o Sheets com funções personalizadas que se conectam a APIs externas, transformando uma planilha simples em uma ferramenta de validação poderosa.

---

## Configuração inicial

Para adicionar o script ao Google Sheets:

1. Abra a planilha no Google Sheets.
2. Acesse **Extensões > Apps Script**.
3. Substitua o conteúdo do editor pelo código abaixo.
4. Salve e autorize as permissões necessárias.

---

## Função de consulta básica

A função principal que consulta a API da CPFHub.io:

```javascript
// Constantes
var API_URL = "https://api.cpfhub.io/cpf";
var TIMEOUT_MS = 10000;

/**
 * Recupera a chave de API armazenada nas propriedades do script.
 * Configure em: Arquivo > Propriedades do projeto > Propriedades do script
 */
function getApiKey() {
 var props = PropertiesService.getScriptProperties();
 var key = props.getProperty("CPFHUB_API_KEY");

 if (!key) {
 throw new Error(
 "Chave de API nao configurada. " +
 "Va em Arquivo > Propriedades do projeto e adicione CPFHUB_API_KEY."
 );
 }

 return key;
}

/**
 * Consulta dados de um CPF na API CPFHub.io.
 * @param {string} cpf - Numero do CPF (com ou sem formatacao).
 * @return {object} Dados do CPF ou mensagem de erro.
 */
function consultarCPF(cpf) {
 var cpfLimpo = String(cpf).replace(/\D/g, "");

 if (cpfLimpo.length !== 11) {
 return { sucesso: false, erro: "CPF deve ter 11 digitos" };
 }

 var apiKey = getApiKey();

 var options = {
 method: "get",
 headers: {
 "x-api-key": apiKey,
 "Accept": "application/json"
 },
 muteHttpExceptions: true,
 followRedirects: true
 };

 try {
 var response = UrlFetchApp.fetch(API_URL + "/" + cpfLimpo, options);
 var statusCode = response.getResponseCode();

 if (statusCode !== 200) {
 return { sucesso: false, erro: "Erro HTTP " + statusCode };
 }

 var dados = JSON.parse(response.getContentText());

 if (!dados.success || !dados.data) {
 return { sucesso: false, erro: "CPF nao encontrado" };
 }

 return {
 sucesso: true,
 dados: dados.data
 };
 } catch (error) {
 return { sucesso: false, erro: "Erro: " + error.message };
 }
}
```

Note que o Google Apps Script usa `UrlFetchApp.fetch` em vez do `fetch` padrão. O timeout é gerenciado pelo próprio runtime do Apps Script (até 6 minutos por execução).

---

## Função personalizada para células

Crie uma função que pode ser usada diretamente como fórmula na planilha:

```javascript
/**
 * Retorna o nome associado a um CPF.
 * Uso na celula: =CONSULTAR_CPF_NOME(A2)
 *
 * @param {string} cpf - Numero do CPF.
 * @return {string} Nome do titular ou mensagem de erro.
 * @customfunction
 */
function CONSULTAR_CPF_NOME(cpf) {
 if (!cpf) return "";

 var resultado = consultarCPF(cpf);

 if (resultado.sucesso) {
 return resultado.dados.name;
 }

 return "ERRO: " + resultado.erro;
}

/**
 * Retorna dados completos de um CPF em colunas separadas.
 * Uso na celula: =CONSULTAR_CPF_COMPLETO(A2)
 * Retorna: [Nome, Genero, Data Nascimento]
 *
 * @param {string} cpf - Numero do CPF.
 * @return {Array} Array com nome, genero e data de nascimento.
 * @customfunction
 */
function CONSULTAR_CPF_COMPLETO(cpf) {
 if (!cpf) return [["", "", ""]];

 var resultado = consultarCPF(cpf);

 if (resultado.sucesso) {
 return [[
 resultado.dados.name,
 resultado.dados.gender === "M" ? "Masculino" : "Feminino",
 resultado.dados.birthDate
 ]];
 }

 return [["ERRO: " + resultado.erro, "", ""]];
}
```

Após salvar o script, use na planilha como qualquer fórmula:

* `=CONSULTAR_CPF_NOME(A2)` — Retorna apenas o nome.
* `=CONSULTAR_CPF_COMPLETO(A2)` — Retorna nome, gênero e data de nascimento em 3 colunas.

---

## Menu personalizado para validação em lote

Adicione um menu na planilha para operações em lote:

```javascript
/**
 * Cria menu personalizado ao abrir a planilha.
 */
function onOpen() {
 var ui = SpreadsheetApp.getUi();
 ui.createMenu("CPFHub")
 .addItem("Validar CPFs selecionados", "validarSelecionados")
 .addItem("Validar toda a coluna A", "validarColunaA")
 .addSeparator()
 .addItem("Configurar chave de API", "configurarChaveAPI")
 .addToUi();
}

/**
 * Dialog para configurar a chave de API.
 */
function configurarChaveAPI() {
 var ui = SpreadsheetApp.getUi();
 var resultado = ui.prompt(
 "Configurar CPFHub.io",
 "Informe sua chave de API:",
 ui.ButtonSet.OK_CANCEL
 );

 if (resultado.getSelectedButton() === ui.Button.OK) {
 var chave = resultado.getResponseText().trim();
 PropertiesService.getScriptProperties().setProperty(
 "CPFHUB_API_KEY",
 chave
 );
 ui.alert("Chave de API configurada com sucesso.");
 }
}

/**
 * Valida os CPFs nas celulas selecionadas.
 * Espera: Coluna A = CPF, escreve resultados nas colunas B, C, D.
 */
function validarSelecionados() {
 var sheet = SpreadsheetApp.getActiveSheet();
 var range = sheet.getActiveRange();
 var valores = range.getValues();
 var primeiraLinha = range.getRow();

 for (var i = 0; i < valores.length; i++) {
 var cpf = String(valores[i][0]).trim();

 if (!cpf) continue;

 var resultado = consultarCPF(cpf);
 var linha = primeiraLinha + i;

 if (resultado.sucesso) {
 sheet.getRange(linha, 2).setValue(resultado.dados.name);
 sheet.getRange(linha, 3).setValue(
 resultado.dados.gender === "M" ? "Masculino" : "Feminino"
 );
 sheet.getRange(linha, 4).setValue(resultado.dados.birthDate);
 sheet.getRange(linha, 5).setValue("Valido");
 } else {
 sheet.getRange(linha, 5).setValue(resultado.erro);
 }

 // Delay para respeitar rate limits
 Utilities.sleep(500);
 }

 SpreadsheetApp.getUi().alert(
 "Validacao concluida. " + valores.length + " CPFs processados."
 );
}

/**
 * Valida todos os CPFs da coluna A (a partir da linha 2).
 */
function validarColunaA() {
 var sheet = SpreadsheetApp.getActiveSheet();
 var ultimaLinha = sheet.getLastRow();

 if (ultimaLinha < 2) {
 SpreadsheetApp.getUi().alert("Nenhum CPF encontrado na coluna A.");
 return;
 }

 var range = sheet.getRange(2, 1, ultimaLinha - 1, 1);
 var valores = range.getValues();
 var processados = 0;

 // Adicionar cabecalhos se nao existirem
 sheet.getRange(1, 2).setValue("Nome");
 sheet.getRange(1, 3).setValue("Genero");
 sheet.getRange(1, 4).setValue("Data Nascimento");
 sheet.getRange(1, 5).setValue("Status");

 for (var i = 0; i < valores.length; i++) {
 var cpf = String(valores[i][0]).trim();

 if (!cpf) continue;

 var resultado = consultarCPF(cpf);
 var linha = i + 2;

 if (resultado.sucesso) {
 sheet.getRange(linha, 2).setValue(resultado.dados.name);
 sheet.getRange(linha, 3).setValue(
 resultado.dados.gender === "M" ? "Masculino" : "Feminino"
 );
 sheet.getRange(linha, 4).setValue(resultado.dados.birthDate);
 sheet.getRange(linha, 5).setValue("Valido");
 } else {
 sheet.getRange(linha, 5).setValue(resultado.erro);
 }

 processados++;
 Utilities.sleep(500);
 }

 SpreadsheetApp.getUi().alert(processados + " CPFs processados.");
}
```

---

## Armazenamento seguro da chave de API

O Google Apps Script oferece o `PropertiesService` para armazenar dados sensíveis:

* **Script Properties** — Compartilhadas entre todos os usuários do script. Ideal para a chave de API.
* **User Properties** — Específicas de cada usuário. Úteis se cada usuário tiver sua própria chave.
* **Document Properties** — Vinculadas ao documento. Evite para segredos, pois qualquer editor do documento pode acessá-las.

A chave de API é armazenada em Script Properties, acessíveis apenas por quem tem acesso de edição ao script.

---

## Limites do Google Apps Script

O Apps Script possui limitações que afetam a validação em lote:

| Limite | Valor |
|----------------------------|--------------------------|
| Tempo de execução | 6 minutos por execução |
| Chamadas UrlFetchApp | 20.000 por dia |
| Tamanho de resposta | 50 MB por chamada |
| Triggers por usuário | 20 por script |

Para 50 consultas mensais (plano gratuito da CPFHub.io), esses limites são mais que suficientes. Para volumes maiores, considere dividir a validação em execuções menores com triggers temporais.

---

## Automação com triggers

Configure triggers para validação automática de novos CPFs adicionados:

```javascript
/**
 * Trigger que executa quando a planilha e editada.
 * Valida automaticamente CPFs adicionados na coluna A.
 */
function onEdit(e) {
 var range = e.range;
 var sheet = range.getSheet();

 // Verificar se a edicao foi na coluna A (CPF)
 if (range.getColumn() !== 1 || range.getRow() < 2) return;

 var cpf = String(range.getValue()).trim();
 if (!cpf || cpf.replace(/\D/g, "").length !== 11) return;

 var resultado = consultarCPF(cpf);
 var linha = range.getRow();

 if (resultado.sucesso) {
 sheet.getRange(linha, 2).setValue(resultado.dados.name);
 sheet.getRange(linha, 3).setValue(
 resultado.dados.gender === "M" ? "Masculino" : "Feminino"
 );
 sheet.getRange(linha, 4).setValue(resultado.dados.birthDate);
 sheet.getRange(linha, 5).setValue("Valido");
 } else {
 sheet.getRange(linha, 5).setValue(resultado.erro);
 }
}
```

---

## Perguntas frequentes

### Por que usar `UrlFetchApp` em vez do `fetch` padrão no Apps Script?

O Google Apps Script roda no lado do servidor do Google, não no navegador, por isso não tem acesso ao `fetch` nativo do JavaScript. O `UrlFetchApp` é a API oficial do Apps Script para requisições HTTP e suporta headers, autenticação e tratamento de erros. Ele também escala automaticamente sem precisar de infraestrutura própria.

### Como armazenar a chave de API sem expô-la no código?

Use o `PropertiesService.getScriptProperties()` para guardar a chave como uma propriedade de script. Assim ela fica fora do código-fonte, não aparece em commits ou compartilhamentos da planilha, e pode ser atualizada pelo menu que configuramos na função `configurarChaveAPI`. Nunca cole a chave diretamente como string no código.

### Quantas consultas de CPF cabem dentro dos limites gratuitos do Apps Script?

O Apps Script permite até 20.000 chamadas ao `UrlFetchApp` por dia, o que é muito superior ao limite da CPFHub.io. No plano Gratuito da CPFHub.io, o gargalo real são as 50 consultas/mês. Ao ultrapassar esse limite, a API não bloqueia — cobra R$0,15 por consulta adicional. Para validações em lote frequentes, o plano Pro (1.000 consultas/mês por R$149) é mais indicado.

### Dá para automatizar a validação sem abrir a planilha manualmente?

Sim. Configure um trigger temporal em **Apps Script > Gatilhos** para executar `validarColunaA` em horários definidos — por exemplo, toda manhã às 8h. O Apps Script executa o script no servidor do Google mesmo com a planilha fechada, validando os CPFs novos adicionados desde a última execução.

### Leia também

- [Como integrar API de CPF com Zapier e Make (Integromat) sem código](https://cpfhub.io/blog/como-integrar-api-de-cpf-com-zapier-e-make-sem-codigo)
- [Como consumir API de CPF em n8n para automações self-hosted](https://cpfhub.io/blog/como-consumir-api-cpf-n8n-automacoes-self-hosted)
- [Como consumir API de CPF em Excel VBA para automação de planilhas](https://cpfhub.io/blog/como-consumir-api-cpf-excel-vba-automacao-planilhas)
- [Como usar API de CPF para enriquecer dados de CRM automaticamente](https://cpfhub.io/blog/como-usar-api-de-cpf-para-enriquecer-dados-de-crm-automaticamente)

---

## Conclusão

Google Apps Script transforma o Google Sheets em uma ferramenta de validação de CPF acessível para equipes não-técnicas. Com funções personalizadas, menus intuitivos e triggers automáticos, qualquer planilha de cadastros pode ser enriquecida com dados validados pela API da [**CPFHub.io**](https://www.cpfhub.io/).

O plano gratuito cobre 50 consultas/mês sem cartão de crédito — suficiente para equipes pequenas que validam cadastros pontualmente. Para times que processam centenas de CPFs por mês, o plano Pro entrega 1.000 consultas por R$149. Consultas além do limite nunca bloqueiam: são cobradas automaticamente a R$0,15 cada.

Crie sua conta em [cpfhub.io](https://www.cpfhub.io/) e comece a validar CPFs direto no Google Sheets.