Validação de CPF em scripts Bash com cURL

Scripts Bash com cURL permitem integrar validação de CPF em automações, cron jobs e pipelines de dados sem dependências externas além do jq para parsing JSON. A abordagem consiste em uma chamada GET autenticada com x-api-key ao endpoint https://api.cpfhub.io/cpf/{CPF}, verificando o código HTTP e o campo success da resposta. O plano gratuito da CPFHub.io cobre 50 consultas mensais; quando o limite é atingido, a API cobra R$ 0,15 por consulta adicional e continua respondendo normalmente.

Introdução

Scripts Bash combinados com cURL formam uma das ferramentas mais versáteis no arsenal de qualquer desenvolvedor ou administrador de sistemas. Para tarefas de validação de CPF, essa combinação é especialmente útil em cenários de automação, processamento em lote, pipelines de CI/CD e monitoramento de dados cadastrais.

1. Pré-requisitos

Bash 4.0 ou superior -- Disponível em praticamente todos os sistemas Linux e macOS.
cURL -- Cliente HTTP de linha de comando, pré-instalado na maioria dos sistemas.
jq -- Processador JSON de linha de comando (altamente recomendado).
Conta na CPFHub.io -- Cadastre-se em cpfhub.io e gere sua API key no painel.

Instalando jq

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# CentOS/RHEL
sudo yum install jq

2. Consulta básica de CPF

O exemplo mais simples de consulta utiliza cURL com os headers necessários:

#!/bin/bash

CPF="12345678900"
API_KEY="SUA_CHAVE_DE_API"

RESPOSTA=$(curl -s -X GET "https://api.cpfhub.io/cpf/${CPF}" \
    -H "x-api-key: ${API_KEY}" \
    -H "Accept: application/json" \
    --max-time 30)

echo "$RESPOSTA" | jq .

A flag -s (silent) suprime a barra de progresso do cURL, e --max-time 30 define um timeout de 30 segundos para evitar que o script fique bloqueado indefinidamente.

3. Script completo com tratamento de erros

Para uso em produção, crie um script robusto com validação de entrada e tratamento de erros:

#!/bin/bash
# consulta_cpf.sh - Consulta de CPF via API CPFHub.io
# Uso: ./consulta_cpf.sh <CPF>

set -euo pipefail

# Configuração
API_KEY="${CPFHUB_API_KEY:-SUA_CHAVE_DE_API}"
API_URL="https://api.cpfhub.io/cpf"
TIMEOUT=30

# Validar entrada
if [ $# -ne 1 ]; then
    echo "Uso: $0 <CPF>" >&2
    exit 1
fi

CPF=$(echo "$1" | tr -dc '0-9')

if [ ${#CPF} -ne 11 ]; then
    echo "Erro: CPF deve conter 11 dígitos." >&2
    exit 1
fi

# Consultar a API
HTTP_CODE=$(curl -s -o /tmp/cpfhub_response.json -w "%{http_code}" \
    -X GET "${API_URL}/${CPF}" \
    -H "x-api-key: ${API_KEY}" \
    -H "Accept: application/json" \
    --max-time ${TIMEOUT})

RESPOSTA=$(cat /tmp/cpfhub_response.json)

# Tratar resposta por código HTTP
case $HTTP_CODE in
    200)
    SUCESSO=$(echo "$RESPOSTA" | jq -r '.success')
    if [ "$SUCESSO" = "true" ]; then
    echo "=== Dados do CPF ==="
    echo "CPF: $(echo "$RESPOSTA" | jq -r '.data.cpf')"
    echo "Nome: $(echo "$RESPOSTA" | jq -r '.data.name')"
    echo "Nome (maiúsculas): $(echo "$RESPOSTA" | jq -r '.data.nameUpper')"
    echo "Gênero: $(echo "$RESPOSTA" | jq -r '.data.gender')"
    echo "Nascimento: $(echo "$RESPOSTA" | jq -r '.data.birthDate')"
    echo "Dia: $(echo "$RESPOSTA" | jq -r '.data.day')"
    echo "Mês: $(echo "$RESPOSTA" | jq -r '.data.month')"
    echo "Ano: $(echo "$RESPOSTA" | jq -r '.data.year')"
    else
    echo "Erro: Consulta retornou success=false." >&2
    exit 1
    fi
    ;;
    400) echo "Erro 400: CPF com formato inválido." >&2; exit 1 ;;
    401) echo "Erro 401: Chave de API inválida." >&2; exit 1 ;;
    500) echo "Erro 500: Erro interno do servidor." >&2; exit 1 ;;
    *) echo "Erro HTTP ${HTTP_CODE}: Resposta inesperada." >&2; exit 1 ;;
esac

# Limpeza
rm -f /tmp/cpfhub_response.json

4. Exemplo de resposta da API

A API da CPFHub.io retorna JSON padronizado com os seguintes campos:

{
    "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 múltiplos CPFs a partir de um arquivo, crie um script de processamento em lote:

#!/bin/bash
# batch_consulta.sh - Processamento em lote de CPFs
# Uso: ./batch_consulta.sh cpfs.txt resultados.csv

set -euo pipefail

ENTRADA="${1:?Informe o arquivo de entrada}"
SAIDA="${2:?Informe o arquivo de saída}"
API_KEY="${CPFHUB_API_KEY:-SUA_CHAVE_DE_API}"
TIMEOUT=30

# Header do CSV
echo "cpf;nome;genero;nascimento;status" > "$SAIDA"

TOTAL=$(wc -l < "$ENTRADA")
ATUAL=0

while IFS= read -r LINHA; do
    ATUAL=$((ATUAL + 1))
    CPF=$(echo "$LINHA" | tr -dc '0-9')

    if [ ${#CPF} -ne 11 ]; then
    echo "${CPF};INVALIDO;;;ERRO_FORMATO" >> "$SAIDA"
    continue
    fi

    RESPOSTA=$(curl -s -X GET "https://api.cpfhub.io/cpf/${CPF}" \
    -H "x-api-key: ${API_KEY}" \
    -H "Accept: application/json" \
    --max-time ${TIMEOUT} 2>/dev/null || echo '{"success":false}')

    SUCESSO=$(echo "$RESPOSTA" | jq -r '.success' 2>/dev/null || echo "false")

    if [ "$SUCESSO" = "true" ]; then
    NOME=$(echo "$RESPOSTA" | jq -r '.data.name')
    GENERO=$(echo "$RESPOSTA" | jq -r '.data.gender')
    NASCIMENTO=$(echo "$RESPOSTA" | jq -r '.data.birthDate')
    echo "${CPF};${NOME};${GENERO};${NASCIMENTO};OK" >> "$SAIDA"
    else
    echo "${CPF};NAO_ENCONTRADO;;;ERRO" >> "$SAIDA"
    fi

    echo "Processado ${ATUAL}/${TOTAL}: ${CPF}"

    sleep 1
done < "$ENTRADA"

echo "Concluído. Resultados salvos em ${SAIDA}"

6. Função Bash reutilizável

Para incluir a consulta de CPF em outros scripts, crie uma função reutilizável:

# cpfhub_functions.sh - Funções para consulta de CPF

cpfhub_consultar() {
    local cpf="$1"
    local api_key="${CPFHUB_API_KEY:-SUA_CHAVE_DE_API}"

    curl -s -X GET "https://api.cpfhub.io/cpf/${cpf}" \
    -H "x-api-key: ${api_key}" \
    -H "Accept: application/json" \
    --max-time 30
}

cpfhub_get_nome() {
    local cpf="$1"
    cpfhub_consultar "$cpf" | jq -r '.data.name // empty'
}

cpfhub_validar() {
    local cpf="$1"
    local resultado=$(cpfhub_consultar "$cpf" | jq -r '.success')
    [ "$resultado" = "true" ]
}

Uso em outros scripts:

#!/bin/bash
source cpfhub_functions.sh

export CPFHUB_API_KEY="SUA_CHAVE_DE_API"

if cpfhub_validar "12345678900"; then
    NOME=$(cpfhub_get_nome "12345678900")
    echo "CPF válido. Titular: ${NOME}"
else
    echo "CPF inválido ou não encontrado."
fi

7. Agendamento com cron

Para executar validações periódicas, utilize o cron:

# Editar crontab
crontab -e

# Executar validação em lote todos os dias às 3h da manhã
0 3 * * * /opt/scripts/batch_consulta.sh /dados/cpfs_novos.txt /dados/resultados_$(date +\%Y\%m\%d).csv >> /var/log/cpfhub_batch.log 2>&1

8. Boas práticas

Use variáveis de ambiente -- Armazene a chave de API em $CPFHUB_API_KEY em vez de incluí-la diretamente nos scripts.
Configure timeouts -- Sempre defina --max-time no cURL para evitar scripts travados.
Trate erros de rede -- Verifique o código de saída do cURL antes de processar a resposta.
Registre logs -- Redirecione a saída dos scripts para arquivos de log para facilitar a depuração.

Perguntas frequentes

Como passar a chave de API com segurança em scripts Bash?

Armazene a chave em uma variável de ambiente (export CPFHUB_API_KEY="sua_chave") ou em um arquivo .env fora do repositório, e carregue-a no script com source .env. Nunca inclua a chave hardcoded no código-fonte nem em arquivos que possam ser versionados no Git. Em sistemas Linux, restrinja as permissões do arquivo com chmod 600 .env.

O cURL retorna erro quando a API atinge o limite de consultas?

Não. A CPFHub.io não bloqueia quando o limite mensal é atingido — ela cobra R$ 0,15 por consulta adicional e continua respondendo com HTTP 200. O script não precisa tratar HTTP 429 para esse cenário. Um código 429 só ocorreria em situações de rate limiting muito agressivo por segundo, não pelo limite mensal do plano.

Como processar um arquivo CSV de CPFs sem travar o script em erros de rede?

Use || echo '{"success":false}' após o comando cURL para garantir um fallback em caso de falha de conexão, e trate o success=false como erro recuperável (registre no CSV de saída e continue o loop). Com set -euo pipefail, erros não tratados ainda interrompem o script, então capture as saídas dos subcomandos críticos explicitamente.

Qual a diferença entre usar jq e processar JSON com grep/sed no Bash?

O jq é o único caminho confiável. grep e sed falham com JSON multilinha, chaves com caracteres especiais ou valores que contêm aspas escapadas. O jq faz parsing semântico do JSON e permite extrair campos com segurança: jq -r '.data.name' retorna o valor sem aspas e com suporte completo a Unicode.

Conclusão

Integrar a validação de CPF em scripts Bash com cURL é uma abordagem prática e eficiente para automação de processos, processamento em lote e tarefas agendadas. A combinação de cURL para requisições HTTP e jq para parsing de JSON torna possível criar pipelines completos de validação de dados cadastrais com poucas linhas de código.

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

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

Como integrar validação de CPF em scripts Bash com cURL