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

// 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 };
    }
}

/**
    * 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, "", ""]];
}

/**
    * 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.");
}

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