# Como consumir API de CPF em PowerShell para automação Windows > Aprenda a consumir uma API de consulta de CPF em PowerShell usando Invoke-RestMethod e Invoke-WebRequest. Exemplos para automação corporativa. **Publicado:** 19/08/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-powershell-para-automacao-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**](https://www.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: ```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`: ```powershell 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**](https://www.cpfhub.io/) retorna um objeto JSON estruturado com todos os dados cadastrais do titular do CPF: ```json { "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: ```powershell 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: ```powershell # 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: ```powershell # 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](https://www.gov.br/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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## Conclusão O PowerShell oferece uma forma nativa e poderosa de consumir APIs REST como a da [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.