Como consumir API de CPF em Excel VBA para automação de 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.

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 para obter sua chave de API gratuita.

Estrutura da planilha

Organize sua planilha da seguinte forma:

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:

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:

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:

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

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:

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:

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:

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:

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

Conclusão

Integrar a API de CPF do 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. Acima do limite por minuto a resposta é HTTP 429, com Retry-After.

Crie sua conta em cpfhub.io e comece a automatizar a validação de CPF no Excel hoje mesmo.