# Como consumir API de CPF em Google Apps Script para automação de planilhas

> Tutorial passo a passo para consumir a API de CPF da CPFHub.io em Google Apps Script e automatizar validações diretamente no Google Sheets.

**Publicado:** 26/04/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-google-apps-script

---


Para consumir a API de CPF da CPFHub.io no Google Apps Script, crie uma função JavaScript que utilize `UrlFetchApp.fetch()` com o endpoint `https://api.cpfhub.io/cpf/{CPF}` e o header `x-api-key`. Em seguida, use a função como fórmula personalizada diretamente nas células do Google Sheets — `=consultarCPF(A2)` — para validar e enriquecer listas de CPFs sem sair da planilha.

## Introdução

Muitas empresas utilizam o Google Sheets como ferramenta central de gestão, controle de cadastros e processamento de dados. Quando surge a necessidade de validar CPFs em massa diretamente na planilha, o Google Apps Script se torna uma solução acessível e eficiente, dispensando a necessidade de ferramentas externas ou conhecimentos avançados de programação.

O Google Apps Script é uma plataforma de scripting baseada em JavaScript que permite estender as funcionalidades dos produtos Google. Com ele, é possível criar funções personalizadas, automatizar tarefas e integrar APIs externas -- incluindo APIs de consulta de CPF.

---

## Pré-requisitos

Antes de começar, você vai precisar de:

* **Conta Google** -- Para acessar o Google Sheets e o editor do Apps Script.

* **Chave de API da CPFHub.io** -- Crie uma conta gratuita em [cpfhub.io](https://www.cpfhub.io/), acesse o painel e gere sua chave de API na seção de configurações.

* **Planilha com CPFs** -- Uma planilha do Google Sheets contendo os CPFs que você deseja consultar.

---

## Criando o script no Google Apps Script

### Passo 1: acessar o editor de scripts

Abra sua planilha no Google Sheets, clique em **Extensões** no menu superior e selecione **Apps Script**. O editor de código será aberto em uma nova aba.

### Passo 2: implementar a função de consulta

No editor do Apps Script, substitua o conteúdo padrão pelo seguinte código:

```javascript
/**
 * Consulta dados de um CPF via API da CPFHub.io
 * @param {string} cpf Número do CPF (com ou sem formatação)
 * @return {string} Nome do titular do CPF
 * @customfunction
 */
function consultarCPF(cpf) {
 if (!cpf) return 'CPF não informado';

 var cpfLimpo = String(cpf).replace(/\D/g, '');

 if (cpfLimpo.length !== 11) return 'CPF inválido';

 var url = 'https://api.cpfhub.io/cpf/' + cpfLimpo;
 var options = {
 method: 'GET',
 headers: {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
 },
 muteHttpExceptions: true
 };

 try {
 var response = UrlFetchApp.fetch(url, options);
 var json = JSON.parse(response.getContentText());

 if (json.success) {
 return json.data.name;
 } else {
 return 'CPF não encontrado';
 }
 } catch (error) {
 return 'Erro na consulta: ' + error.message;
 }
}
```

### Passo 3: salvar e autorizar

Salve o projeto com Ctrl+S (ou Cmd+S no Mac). Na primeira execução, o Google solicitará autorização para que o script faça requisições HTTP externas. Aceite as permissões necessárias.

---

## Usando a função na planilha

Após salvar o script, volte à planilha e utilize a função como qualquer outra fórmula do Google Sheets:

```
=consultarCPF(A2)
```

Onde `A2` é a célula que contém o número do CPF. A função irá consultar a API e retornar o nome do titular diretamente na célula.

---

## Função avançada: retornando múltiplos campos

Se você precisa obter mais informações além do nome, crie uma versão expandida da função que retorna múltiplos campos em colunas adjacentes:

```javascript
/**
 * Consulta dados completos de um CPF via API da CPFHub.io
 * @param {string} cpf Número do CPF
 * @return {Array} Array com nome, gênero e data de nascimento
 * @customfunction
 */
function consultarCPFCompleto(cpf) {
 if (!cpf) return [['CPF não informado', '', '']];

 var cpfLimpo = String(cpf).replace(/\D/g, '');

 if (cpfLimpo.length !== 11) return [['CPF inválido', '', '']];

 var url = 'https://api.cpfhub.io/cpf/' + cpfLimpo;
 var options = {
 method: 'GET',
 headers: {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
 },
 muteHttpExceptions: true
 };

 try {
 var response = UrlFetchApp.fetch(url, options);
 var json = JSON.parse(response.getContentText());

 if (json.success) {
 return [[
 json.data.name,
 json.data.gender === 'M' ? 'Masculino' : 'Feminino',
 json.data.birthDate
 ]];
 } else {
 return [['Não encontrado', '', '']];
 }
 } catch (error) {
 return [['Erro: ' + error.message, '', '']];
 }
}
```

Na planilha, use a fórmula e ela preencherá automaticamente três colunas:

```
=consultarCPFCompleto(A2)
```

| CPF | Nome | Gênero | Data de Nascimento |
| --- | --- | --- | --- |
| 12345678900 | João da Silva | Masculino | 15/06/1990 |

---

## Processamento em lote com menu personalizado

Para consultar vários CPFs de uma vez sem sobrecarregar a API, crie um menu personalizado com processamento sequencial e respeito ao rate limit:

```javascript
function onOpen() {
 var ui = SpreadsheetApp.getUi();
 ui.createMenu('CPFHub')
 .addItem('Consultar CPFs selecionados', 'consultarEmLote')
 .addToUi();
}

function consultarEmLote() {
 var planilha = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
 var ultimaLinha = planilha.getLastRow();

 for (var i = 2; i <= ultimaLinha; i++) {
 var cpf = planilha.getRange(i, 1).getValue();

 if (!cpf) continue;

 var cpfLimpo = String(cpf).replace(/\D/g, '');
 if (cpfLimpo.length !== 11) {
 planilha.getRange(i, 2).setValue('CPF inválido');
 continue;
 }

 var url = 'https://api.cpfhub.io/cpf/' + cpfLimpo;
 var options = {
 method: 'GET',
 headers: {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
 },
 muteHttpExceptions: true
 };

 try {
 var response = UrlFetchApp.fetch(url, options);
 var json = JSON.parse(response.getContentText());

 if (json.success) {
 planilha.getRange(i, 2).setValue(json.data.name);
 planilha.getRange(i, 3).setValue(json.data.gender);
 planilha.getRange(i, 4).setValue(json.data.birthDate);
 } else {
 planilha.getRange(i, 2).setValue('Não encontrado');
 }
 } catch (error) {
 planilha.getRange(i, 2).setValue('Erro');
 }

 // Respeitar rate limit: aguardar 2 segundos entre consultas (plano gratuito)
 Utilities.sleep(2000);
 }

 SpreadsheetApp.getUi().alert('Consulta em lote finalizada.');
}
```

Após salvar e recarregar a planilha, um menu "CPFHub" aparecerá na barra de menus. Selecione os CPFs na coluna A e clique em "Consultar CPFs selecionados" para processar todos.

---

## Cuidados importantes

### Respeitar o rate limit

O plano gratuito da [**CPFHub.io**](https://www.cpfhub.io/) inclui 50 consultas por mês — suficiente para testes e planilhas com baixo volume. Para consultas em lote maiores, considere o plano Pro, com 1.000 consultas mensais por R$ 149. O código acima já inclui um `Utilities.sleep(2000)` entre chamadas para evitar sobrecarga.

### Proteger a chave de API

Evite inserir a chave de API diretamente no código. Uma alternativa mais segura é armazená-la nas propriedades do script:

```javascript
// Configurar a chave (executar uma vez)
function configurarChave() {
 PropertiesService.getScriptProperties().setProperty('CPFHUB_API_KEY', 'SUA_CHAVE_DE_API');
}

// Recuperar a chave no código
function getApiKey() {
 return PropertiesService.getScriptProperties().getProperty('CPFHUB_API_KEY');
}
```

### Controlar o consumo de consultas

Com 50 consultas gratuitas por mês, é importante controlar o uso. Adicione um contador para evitar exceder o limite:

```javascript
function incrementarContador() {
 var props = PropertiesService.getScriptProperties();
 var contador = parseInt(props.getProperty('consultas_mes') || '0');
 contador++;
 props.setProperty('consultas_mes', String(contador));
 return contador;
}
```

### Conformidade com a LGPD

Ao consultar CPFs e armazenar dados pessoais em planilhas, certifique-se de que o acesso à planilha é restrito apenas a pessoas autorizadas. A LGPD exige que dados pessoais sejam tratados com finalidade específica e proteção adequada.

---

## Perguntas frequentes

### O que é necessário para implementar validação de CPF neste contexto?
A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

### A API CPFHub.io funciona para todos os volumes de consulta?
Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

### Como garantir conformidade com a LGPD ao usar uma API de CPF?
Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade.

### Quanto tempo leva para integrar a API CPFHub.io?
A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## Conclusão

Integrar a API de CPF da CPFHub.io com o Google Apps Script é uma forma prática e acessível de automatizar validações de CPF diretamente no Google Sheets. Com poucas linhas de código, é possível criar funções personalizadas, processar lotes de CPFs e obter dados cadastrais sem sair da planilha.

Essa abordagem é especialmente útil para equipes que já utilizam o Google Sheets como ferramenta de gestão e precisam de uma solução rápida para validação de cadastros, emissão de documentos fiscais ou controle de colaboradores.

Crie sua conta gratuitamente em [cpfhub.io](https://www.cpfhub.io/) e integre em minutos.