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

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, 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:

/**
    * 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:

/**
    * 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)

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:

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 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:

// 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:

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 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.

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 e integre em minutos.