Como consumir API de CPF em PowerShell para automação Windows

PowerShell consome a API da CPFHub.io com apenas algumas linhas usando Invoke-RestMethod — sem dependências externas, com tratamento de erros nativo e integração direta ao Task Scheduler para automações corporativas recorrentes. É a forma mais rápida de validar CPFs em lote em ambientes Windows sem sair do ecossistema Microsoft.

Introdução

O PowerShell é a principal ferramenta de automação em ambientes Windows, amplamente utilizada por equipes de TI, DevOps e desenvolvimento em empresas de todos os portes. Com cmdlets nativos para requisições HTTP como Invoke-RestMethod e Invoke-WebRequest, o PowerShell é uma excelente opção para integrar APIs de consulta de CPF em fluxos de trabalho corporativos.

1. Pré-requisitos

• PowerShell 5.1 ou superior -- Incluído no Windows 10/11 e Windows Server 2016+. O PowerShell 7 (Core) também é suportado e funciona em Linux e macOS.

• Conta na CPFHub.io -- Cadastre-se em CPFHub.io e gere uma API key no painel para autenticar suas requisições.

2. Consulta básica com Invoke-RestMethod

O Invoke-RestMethod é o cmdlet mais prático para consumir APIs REST, pois já converte automaticamente a resposta JSON em objetos PowerShell:

$cpf = "12345678900"
$apiKey = "SUA_CHAVE_DE_API"
$url = "https://api.cpfhub.io/cpf/$cpf"

$headers = @{
    "x-api-key" = $apiKey
    "Accept" = "application/json"
}

$response = Invoke-RestMethod -Uri $url -Method Get -Headers $headers -TimeoutSec 30

if ($response.success) {
    Write-Host "Nome: $($response.data.name)"
    Write-Host "Nome (maiusculas): $($response.data.nameUpper)"
    Write-Host "Genero: $($response.data.gender)"
    Write-Host "Nascimento: $($response.data.birthDate)"
    Write-Host "Dia: $($response.data.day), Mes: $($response.data.month), Ano: $($response.data.year)"
} else {
    Write-Warning "Consulta nao retornou dados."
}

O parâmetro -TimeoutSec 30 define um timeout de 30 segundos para a requisição, evitando que o script fique bloqueado indefinidamente.

3. Consulta com Invoke-WebRequest e tratamento de erros

Para maior controle sobre a resposta HTTP, use Invoke-WebRequest:

function Get-CpfData {
    [CmdletBinding()]
    param(
    [Parameter(Mandatory)]
    [ValidatePattern('^\d{11}$')]
    [string]$Cpf,

    [Parameter(Mandatory)]
    [string]$ApiKey
    )

    $url = "https://api.cpfhub.io/cpf/$Cpf"

    $headers = @{
    "x-api-key" = $ApiKey
    "Accept" = "application/json"
    }

    try {
    $response = Invoke-WebRequest -Uri $url -Method Get -Headers $headers -TimeoutSec 30 -ErrorAction Stop
    $data = $response.Content | ConvertFrom-Json

    if ($data.success) {
    return $data.data
    } else {
    Write-Warning "A API retornou success=false para o CPF $Cpf."
    return $null
    }
    }
    catch {
    $statusCode = $_.Exception.Response.StatusCode.Value__

    switch ($statusCode) {
    400 { Write-Error "Erro 400: CPF com formato invalido." }
    401 { Write-Error "Erro 401: Chave de API invalida." }
    500 { Write-Error "Erro 500: Erro interno do servidor." }
    default { Write-Error "Erro HTTP $statusCode`: $($_.Exception.Message)" }
    }

    return $null
    }
}

# Uso
$resultado = Get-CpfData -Cpf "12345678900" -ApiKey "SUA_CHAVE_DE_API"

if ($resultado) {
    Write-Host "Nome: $($resultado.name)"
    Write-Host "CPF: $($resultado.cpf)"
}

4. Exemplo de resposta da API

A API da CPFHub.io retorna um objeto JSON estruturado com todos os dados cadastrais do titular do CPF:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success -- Indica se a consulta foi bem-sucedida.
• name / nameUpper -- Nome completo do titular.
• gender -- Gênero (M ou F).
• birthDate -- Data de nascimento no formato dd/mm/aaaa.
• day, month, year -- Componentes da data separados.

5. Processamento em lote

Para validar uma lista de CPFs a partir de um arquivo CSV:

function Invoke-CpfBatch {
    [CmdletBinding()]
    param(
    [Parameter(Mandatory)]
    [string]$InputFile,

    [Parameter(Mandatory)]
    [string]$OutputFile,

    [Parameter(Mandatory)]
    [string]$ApiKey
    )

    $cpfs = Import-Csv -Path $InputFile -Delimiter ";"
    $resultados = @()
    $total = $cpfs.Count
    $atual = 0

    foreach ($item in $cpfs) {
    $atual++
    Write-Progress -Activity "Validando CPFs" -Status "$atual de $total" -PercentComplete (($atual / $total) * 100)

    $cpfLimpo = $item.cpf -replace '\D', ''

    if ($cpfLimpo.Length -ne 11) {
    $resultados += [PSCustomObject]@{
    CPF = $cpfLimpo
    Nome = ""
    Genero = ""
    Nascimento = ""
    Status = "FORMATO_INVALIDO"
    }
    continue
    }

    $dados = Get-CpfData -Cpf $cpfLimpo -ApiKey $ApiKey

    if ($dados) {
    $resultados += [PSCustomObject]@{
    CPF = $dados.cpf
    Nome = $dados.name
    Genero = $dados.gender
    Nascimento = $dados.birthDate
    Status = "OK"
    }
    } else {
    $resultados += [PSCustomObject]@{
    CPF = $cpfLimpo
    Nome = ""
    Genero = ""
    Nascimento = ""
    Status = "ERRO"
    }
    }

    # Respeitar rate limit do plano gratuito (1 req a cada 2 segundos)
    Start-Sleep -Seconds 2
    }

    $resultados | Export-Csv -Path $OutputFile -Delimiter ";" -NoTypeInformation -Encoding UTF8
    Write-Host "Processamento concluido. Resultados em $OutputFile"
}

# Uso
Invoke-CpfBatch -InputFile "C:\dados\cpfs.csv" -OutputFile "C:\dados\resultados.csv" -ApiKey "SUA_CHAVE_DE_API"

6. Armazenamento seguro da chave de API

No Windows, utilize o Credential Manager para armazenar a chave de forma segura:

# Salvar a chave (executar uma vez)
$credential = New-Object System.Management.Automation.PSCredential(
    "cpfhub",
    (ConvertTo-SecureString "SUA_CHAVE_DE_API" -AsPlainText -Force)
)
$credential | Export-Clixml -Path "$env:USERPROFILE\.cpfhub_credential.xml"

# Recuperar a chave em scripts
$credential = Import-Clixml -Path "$env:USERPROFILE\.cpfhub_credential.xml"
$apiKey = $credential.GetNetworkCredential().Password

7. Agendamento com Task Scheduler

Para executar validações periódicas no Windows, utilize o Task Scheduler:

# Criar tarefa agendada para executar diariamente às 3h
$action = New-ScheduledTaskAction -Execute "powershell.exe" `
    -Argument "-ExecutionPolicy Bypass -File C:\scripts\batch_cpf.ps1"

$trigger = New-ScheduledTaskTrigger -Daily -At 3:00AM

$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -DontStopOnIdleEnd

Register-ScheduledTask -TaskName "CPFHub_BatchValidation" `
    -Action $action -Trigger $trigger -Settings $settings `
    -Description "Validação em lote de CPFs via CPFHub.io"

8. Boas práticas

• Use variáveis de ambiente ou Credential Manager -- Nunca inclua chaves de API diretamente no código dos scripts.

• Configure timeouts -- Sempre defina -TimeoutSec nas requisições para evitar scripts travados.

• Implemente logging -- Utilize Start-Transcript para registrar a execução completa do script.

• Valide o CPF antes de enviar -- Confirme que o CPF possui 11 dígitos antes de fazer a requisição à API.

• Respeite rate limits -- O plano gratuito permite 1 requisição a cada 2 segundos. O plano Pro (R$ 149/mês) permite 1 requisição por segundo com 1.000 consultas mensais; consultas excedentes são cobradas a R$0,15 cada, sem interrupção do serviço.

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

O PowerShell oferece uma forma nativa e poderosa de consumir APIs REST como a da CPFHub.io, sem precisar instalar bibliotecas externas ou ferramentas adicionais.

A CPFHub.io oferece uma API REST com conformidade LGPD, tempo de resposta de aproximadamente 900ms e 99,9% de uptime. Com mais de 1.300 empresas ativas e 10 milhões de CPFs consultados, a plataforma é confiável para ambientes corporativos.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.