# Como consumir API de CPF em Excel VBA para automação de planilhas > Aprenda a consumir a API de CPF diretamente no Excel com VBA. Automatize a validação de cadastros em planilhas com exemplos práticos. **Publicado:** 10/10/2026 **Autor:** Lucas Vieira **URL:** https://www.cpfhub.io/blog/como-consumir-api-cpf-excel-vba-automacao-planilhas --- Para consumir a API de CPF no Excel via VBA, use o objeto `MSXML2.XMLHTTP.6.0` para fazer uma requisição GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A resposta chega em ~150 ms com nome, gênero e data de nascimento, que o VBA escreve diretamente nas células correspondentes. A referência completa do VBA está na [documentação oficial da Microsoft](https://learn.microsoft.com/pt-br/office/vba/api/overview/excel). Muitas empresas brasileiras ainda dependem do Microsoft Excel como ferramenta central para gestão de cadastros, conciliação financeira e controle de clientes. Planilhas com milhares de linhas de CPFs são uma realidade em departamentos financeiros, jurídicos e de compliance. O problema surge quando é necessário validar ou enriquecer esses dados manualmente — um processo lento, sujeito a erros e que consome horas de trabalho. A boa notícia é que o Excel oferece o VBA (Visual Basic for Applications), uma linguagem de programação embutida que permite automatizar tarefas repetitivas, incluindo chamadas a APIs externas. --- ## Por que automatizar a validação de CPF no Excel ### O custo do processo manual Equipes que validam CPFs manualmente enfrentam diversos problemas. Copiar e colar números em sites de consulta, um por um, é ineficiente e propenso a erros de digitação. Em planilhas com 500 ou mais registros, esse processo pode levar dias inteiros de trabalho. ### Benefícios da automação com VBA Com VBA, é possível percorrer todas as linhas de uma planilha, enviar cada CPF para a API e preencher automaticamente colunas com o nome do titular, data de nascimento e gênero. Os principais benefícios incluem: - **Velocidade** — centenas de consultas em minutos, não em dias. - **Precisão** — eliminação de erros de digitação e cópia. - **Padronização** — dados retornados em formato consistente. - **Rastreabilidade** — cada consulta fica registrada na própria planilha. --- ## Pré-requisitos e configuração do ambiente ### Habilitando o VBA no Excel Para acessar o editor VBA, pressione `Alt + F11` no Excel. Caso a guia "Desenvolvedor" não esteja visível, ative-a em **Arquivo > Opções > Personalizar Faixa de Opções > Desenvolvedor**. ### Adicionando referências necessárias No editor VBA, vá em **Ferramentas > Referências** e marque as seguintes bibliotecas: - **Microsoft XML, v6.0** (MSXML2) — para realizar requisições HTTP. - **Microsoft Scripting Runtime** — para manipulação de dicionários (opcional, mas útil para parsing JSON). ### Obtendo sua chave de API Cadastre-se em [**CPFHub.io**](https://www.cpfhub.io/) para obter sua chave de API gratuita. --- ## Estrutura da planilha Organize sua planilha da seguinte forma: | Coluna A | Coluna B | Coluna C | Coluna D | Coluna E | |----------|----------|----------|----------|----------| | CPF | Nome | Gênero | Nascimento | Status | | 12345678901 | | | | | | 98765432100 | | | | | A coluna A contém os CPFs a serem consultados. As colunas B a E serão preenchidas automaticamente pelo VBA com os dados retornados pela API. --- ## Código VBA completo para consulta de CPF ### Módulo principal Abra o editor VBA, insira um novo módulo (**Inserir > Módulo**) e cole o seguinte código: ```vba Option Explicit Private Const API_URL As String = "https://api.cpfhub.io/cpf/" Private Const API_KEY As String = "SUA_API_KEY_AQUI" Private Const TIMEOUT_MS As Long = 10000 ' Timeout de 10 segundos Sub ConsultarCPFs() Dim ws As Worksheet Set ws = ThisWorkbook.Sheets(1) Dim lastRow As Long lastRow = ws.Cells(ws.Rows.Count, "A").End(xlUp).Row Dim i As Long For i = 2 To lastRow Dim cpf As String cpf = Trim(CStr(ws.Cells(i, 1).Value)) ' Remove pontuação do CPF cpf = Replace(cpf, ".", "") cpf = Replace(cpf, "-", "") If Len(cpf) = 11 And IsNumeric(cpf) Then Dim resultado As String resultado = ChamarAPICPF(cpf) If resultado <> "ERRO" Then Call PreencherDados(ws, i, resultado) ws.Cells(i, 5).Value = "OK" Else ws.Cells(i, 5).Value = "ERRO" End If Else ws.Cells(i, 5).Value = "CPF INVALIDO" End If ' Pausa de 200ms entre requisições para respeitar rate limit Application.Wait Now + TimeValue("00:00:01") * 0.2 DoEvents Next i MsgBox "Consulta finalizada!", vbInformation End Sub Function ChamarAPICPF(cpf As String) As String On Error GoTo ErrorHandler Dim http As Object Set http = CreateObject("MSXML2.XMLHTTP.6.0") http.Open "GET", API_URL & cpf, False http.setRequestHeader "x-api-key", API_KEY http.setRequestHeader "Accept", "application/json" http.setTimeouts TIMEOUT_MS, TIMEOUT_MS, TIMEOUT_MS, TIMEOUT_MS http.Send If http.Status = 200 Then ChamarAPICPF = http.responseText Else ChamarAPICPF = "ERRO" End If Set http = Nothing Exit Function ErrorHandler: ChamarAPICPF = "ERRO" End Function Sub PreencherDados(ws As Worksheet, row As Long, json As String) ' Parser simples para extrair valores do JSON ws.Cells(row, 2).Value = ExtrairValorJSON(json, "name") ws.Cells(row, 3).Value = ExtrairValorJSON(json, "gender") ws.Cells(row, 4).Value = ExtrairValorJSON(json, "birthDate") End Sub Function ExtrairValorJSON(json As String, chave As String) As String Dim pattern As String pattern = """" & chave & """:""" Dim posInicio As Long posInicio = InStr(json, pattern) If posInicio > 0 Then posInicio = posInicio + Len(pattern) Dim posFim As Long posFim = InStr(posInicio, json, """") ExtrairValorJSON = Mid(json, posInicio, posFim - posInicio) Else ExtrairValorJSON = "" End If End Function ``` ### Testando via cURL antes de integrar Antes de rodar o VBA, confirme que sua chave funciona com um teste via terminal: ```bash curl --max-time 10 -X GET "https://api.cpfhub.io/cpf/12345678901" \ -H "x-api-key: SUA_API_KEY_AQUI" \ -H "Accept: application/json" ``` A resposta esperada: ```json { "success": true, "data": { "cpf": "12345678901", "name": "João da Silva", "nameUpper": "JOAO DA SILVA", "gender": "M", "birthDate": "01/01/1990", "day": "01", "month": "01", "year": "1990" } } ``` --- ## Tratamento de erros e boas práticas ### Lidando com falhas de rede O código já inclui um timeout de 10 segundos por requisição. Para maior robustez, implemente uma lógica de retry: ```vba Function ChamarAPICPFComRetry(cpf As String, tentativas As Integer) As String Dim i As Integer For i = 1 To tentativas Dim resultado As String resultado = ChamarAPICPF(cpf) If resultado <> "ERRO" Then ChamarAPICPFComRetry = resultado Exit Function End If Application.Wait Now + TimeValue("00:00:02") ' Espera 2s entre retries Next i ChamarAPICPFComRetry = "ERRO" End Function ``` ### Respeitando limites do plano O plano gratuito permite 50 consultas por mês. Para evitar desperdício, adicione uma contagem no início da macro: ```vba Dim totalConsultas As Long totalConsultas = lastRow - 1 If totalConsultas > 50 Then Dim resposta As VbMsgBoxResult resposta = MsgBox("Serão realizadas " & totalConsultas & _ " consultas. Deseja continuar?", vbYesNo + vbQuestion) If resposta = vbNo Then Exit Sub End If ``` ### Protegendo a chave de API Nunca compartilhe a planilha com a chave de API exposta no código. Uma alternativa é armazenar a chave em uma célula protegida ou em uma variável de ambiente do Windows. --- ## Otimizações avançadas ### Consulta assíncrona com barra de progresso Para planilhas grandes, adicione uma barra de progresso na StatusBar do Excel: ```vba Application.StatusBar = "Consultando CPF " & i - 1 & " de " & lastRow - 1 & "..." ``` ### Cache local para evitar consultas duplicadas Se a planilha contém CPFs repetidos, use um dicionário para cachear resultados: ```vba Dim cache As Object Set cache = CreateObject("Scripting.Dictionary") If cache.Exists(cpf) Then resultado = cache(cpf) Else resultado = ChamarAPICPF(cpf) If resultado <> "ERRO" Then cache.Add cpf, resultado End If ``` ### Exportando resultados para CSV Após a consulta, exporte os dados validados para CSV para integração com outros sistemas: ```vba Sub ExportarCSV() Dim caminho As String caminho = ThisWorkbook.Path & "\cpfs_validados.csv" ThisWorkbook.Sheets(1).Copy ActiveWorkbook.SaveAs caminho, xlCSV ActiveWorkbook.Close False End Sub ``` --- ## Casos de uso práticos ### Departamento financeiro Validação em massa de CPFs de fornecedores antes de emitir notas fiscais, garantindo que os dados cadastrais estejam corretos e atualizados. ### Recursos humanos Verificação de CPFs de candidatos durante processos seletivos, automatizando a conferência de dados pessoais. ### Compliance e auditoria Varredura periódica de bases de clientes para identificar cadastros com CPFs inválidos ou inconsistentes, gerando relatórios automatizados. --- ## Perguntas frequentes ### O VBA consegue consumir APIs REST com autenticação por header? Sim. O objeto `MSXML2.XMLHTTP.6.0` suporta o método `setRequestHeader`, que permite enviar qualquer header HTTP — inclusive o `x-api-key` exigido pela CPFHub.io. Basta chamar `http.setRequestHeader "x-api-key", SUA_CHAVE` antes de `http.Send`. Certifique-se de que a referência **Microsoft XML, v6.0** está marcada em **Ferramentas > Referências** no editor VBA. ### Como evitar exceder o limite de consultas no plano gratuito? Adicione um contador antes de iniciar o loop e exiba uma caixa de confirmação quando o total de CPFs ultrapassar 50. Sim, no Grátis. A cota de 50 créditos mensais, quando acaba, pausa as consultas com HTTP 403 e a mensagem "Limite de créditos excedido". Um plano pago pode continuar se tiver excedente — o valor está na [página de preços](https://www.cpfhub.io/precos) — e o teto de chamadas por minuto responde HTTP 429 com Retry-After. Para equipes que validam frequentemente, o plano Pro (1.000 créditos/mês por R$149) elimina essa preocupação. ### O Excel fecha a conexão HTTP corretamente após cada consulta? No código fornecido, `Set http = Nothing` libera o objeto XMLHTTP ao final de cada chamada. Para garantir que a conexão não fique pendente em caso de erro, o tratamento `On Error GoTo ErrorHandler` com `Set http = Nothing` no bloco de erro também é essencial. Em loops longos, use `DoEvents` periodicamente para que o Excel processe eventos de interface e evite travar. ### Dá para rodar a macro automaticamente ao abrir a planilha? Sim. Crie uma sub chamada `Workbook_Open` no módulo **EstaPasta_de_trabalho** e chame `ConsultarCPFs` de dentro dela. Tenha cuidado: isso iniciará consultas à API toda vez que a planilha for aberta, consumindo o limite do plano. O ideal é usar um botão ou um menu personalizado para acionar a macro manualmente. ### 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 Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets) - [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 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 Integrar a API de CPF do [**CPFHub.io**](https://www.cpfhub.io/) ao Excel via VBA transforma planilhas estáticas em ferramentas de validação automática — sem dependência de sistemas externos ou licenças adicionais. O processo de consulta leva ~150 ms por CPF, e o retorno com nome, gênero e data de nascimento é gravado diretamente nas células da planilha. O plano gratuito cobre 50 créditos/mês sem cartão de crédito. Para departamentos com demandas maiores, o plano Pro entrega 1.000 créditos por R$149/mês. Esgotar a franquia do Grátis interrompe as consultas com HTTP 403 ("Limite de créditos excedido"). No plano pago, o excedente depende da faixa e está na [página de preços](https://www.cpfhub.io/precos). Acima do limite por minuto a resposta é HTTP 429, com Retry-After. Crie sua conta em [cpfhub.io](https://www.cpfhub.io/) e comece a automatizar a validação de CPF no Excel hoje mesmo.