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

> Aprenda a integrar validação de CPF em scripts Bash usando cURL e jq. Exemplos para automação, cron jobs e pipelines de dados.

**Publicado:** 04/08/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-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](https://www.cpfhub.io/) e gere sua API key no painel.

### Instalando jq

```bash
# 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:

```bash
#!/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:

```bash
#!/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:

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

```bash
#!/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:

```bash
# 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:

```bash
#!/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:

```bash
# 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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [APIs de CPF grátis e tempo de resposta: o que esperar](https://cpfhub.io/blog/apis-de-cpf-gratis-e-tempo-de-resposta-o-que-esperar)
- [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)

---

## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.