# Como implementar health check para monitorar disponibilidade da API de CPF

> Aprenda a implementar health checks automatizados para monitorar a disponibilidade e o tempo de resposta da API de consulta de CPF.

**Publicado:** 31/08/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/implementar-health-check-monitorar-disponibilidade-api-cpf

---


Implementar um health check para monitorar a disponibilidade da API de CPF garante que sua aplicação detecte falhas antes que os usuários as percebam. Com a CPFHub.io — que responde em cerca de 900ms e oferece 99,9% de uptime —, um monitoramento bem configurado transforma degradações silenciosas em alertas acionáveis, protegendo processos críticos de onboarding e concessão de crédito.

## Introdução

Dependências externas como APIs de terceiros podem falhar a qualquer momento. Quando sua aplicação depende de uma API de consulta de CPF para processos críticos como onboarding e concessao de crédito, saber que a API esta disponível antes que os usuários encontrem problemas e fundamental.

---

## O que é um health check

Um health check e uma verificação periódica e automatizada que testa se um serviço esta funcionando corretamente. Para uma API de CPF, isso inclui:

* **Disponibilidade** -- A API esta respondendo?

* **Latência** -- O tempo de resposta esta dentro do esperado?

* **Autenticação** -- A API key continua válida?

* **Formato da resposta** -- A estrutura do JSON esta correta?

---

## Health check básico com cURL

A forma mais simples de verificar a disponibilidade:

```bash
curl -X GET https://api.cpfhub.io/cpf/00000000000 \
 -H "x-api-key: SUA_CHAVE_DE_API" \
 -H "Accept: application/json" \
 --max-time 15 \
 -w "\nHTTP_CODE: %{http_code}\nTIME: %{time_total}s\n" \
 -o /dev/null -s
```

Se o HTTP_CODE for 200 ou 404 (CPF não encontrado, mas API respondendo), o serviço esta disponível.

---

## Health check em Python

Uma implementação mais completa que verifica multiplos aspectos:

```python
import requests
import time
from datetime import datetime
from enum import Enum

class HealthStatus(Enum):
 HEALTHY = 'healthy'
 DEGRADED = 'degraded'
 UNHEALTHY = 'unhealthy'

class CPFHealthChecker:
 def __init__(self, api_key, latencia_limite_ms=3000):
 self.api_key = api_key
 self.latencia_limite = latencia_limite_ms
 self.session = requests.Session()
 self.session.headers.update({
 'x-api-key': api_key,
 'Accept': 'application/json'
 })

 def verificar(self):
 resultado = {
 'timestamp': datetime.utcnow().isoformat(),
 'status': HealthStatus.UNHEALTHY.value,
 'latencia_ms': None,
 'http_status': None,
 'resposta_valida': False,
 'detalhes': ''
 }

 try:
 inicio = time.perf_counter()
 response = self.session.get(
 'https://api.cpfhub.io/cpf/00000000000',
 timeout=15
 )
 fim = time.perf_counter()

 latencia = (fim - inicio) * 1000
 resultado['latencia_ms'] = round(latencia, 2)
 resultado['http_status'] = response.status_code

 # Verificar se a resposta e JSON valido
 try:
 data = response.json()
 resultado['resposta_valida'] = 'success' in data
 except ValueError:
 resultado['detalhes'] = 'Resposta nao e JSON valido'
 return resultado

 # Determinar status
 if response.status_code in [200, 404] and resultado['resposta_valida']:
 if latencia <= self.latencia_limite:
 resultado['status'] = HealthStatus.HEALTHY.value
 else:
 resultado['status'] = HealthStatus.DEGRADED.value
 resultado['detalhes'] = f'Latencia acima do limite ({latencia:.0f}ms > {self.latencia_limite}ms)'
 elif response.status_code == 401:
 resultado['detalhes'] = 'API key invalida'
 else:
 resultado['detalhes'] = f'Status inesperado: {response.status_code}'

 except requests.exceptions.Timeout:
 resultado['detalhes'] = 'Timeout na requisicao'
 except requests.exceptions.ConnectionError:
 resultado['detalhes'] = 'Erro de conexao'
 except Exception as e:
 resultado['detalhes'] = str(e)

 return resultado

# Uso
checker = CPFHealthChecker('SUA_CHAVE_DE_API')
status = checker.verificar()
print(f'Status: {status["status"]}')
print(f'Latencia: {status["latencia_ms"]}ms')
```

---

## Health check em Node.js

```javascript
class CPFHealthChecker {
 constructor(apiKey, latenciaLimiteMs = 3000) {
 this.apiKey = apiKey;
 this.latenciaLimite = latenciaLimiteMs;
 }

 async verificar() {
 const resultado = {
 timestamp: new Date().toISOString(),
 status: 'unhealthy',
 latenciaMs: null,
 httpStatus: null,
 respostaValida: false,
 detalhes: ''
 };

 try {
 const inicio = performance.now();

 const response = await fetch('https://api.cpfhub.io/cpf/00000000000', {
 method: 'GET',
 headers: {
 'x-api-key': this.apiKey,
 'Accept': 'application/json'
 },
 signal: AbortSignal.timeout(15000)
 });

 const fim = performance.now();
 const latencia = fim - inicio;

 resultado.latenciaMs = Math.round(latencia * 100) / 100;
 resultado.httpStatus = response.status;

 const data = await response.json();
 resultado.respostaValida = 'success' in data;

 if ([200, 404].includes(response.status) && resultado.respostaValida) {
 resultado.status = latencia <= this.latenciaLimite ? 'healthy' : 'degraded';
 }
 } catch (error) {
 resultado.detalhes = error.message;
 }

 return resultado;
 }
}

// Uso
const checker = new CPFHealthChecker(process.env.CPFHUB_API_KEY);
const status = await checker.verificar();
console.log(JSON.stringify(status, null, 2));
```

---

## Agendando verificações periódicas

### Com cron (Linux/macOS)

```bash
# Verificar a cada 5 minutos
*/5 * * * * /usr/bin/python3 /opt/scripts/health_check_cpf.py >> /var/log/cpf_health.log 2>&1
```

### Com Node.js (setInterval)

```javascript
const INTERVALO_MS = 5 * 60 * 1000; // 5 minutos

const checker = new CPFHealthChecker(process.env.CPFHUB_API_KEY);

setInterval(async () => {
 const status = await checker.verificar();
 console.log(`[${status.timestamp}] Status: ${status.status} | Latencia: ${status.latenciaMs}ms`);

 if (status.status === 'unhealthy') {
 // Disparar alerta (e-mail, Slack, PagerDuty)
 await enviarAlerta(status);
 }
}, INTERVALO_MS);
```

---

## Expondo o health check como endpoint

Crie um endpoint na sua aplicação que expoe o status das dependências:

```python
from flask import Flask, jsonify

app = Flask(__name__)
checker = CPFHealthChecker('SUA_CHAVE_DE_API')

@app.route('/health')
def health():
 status_cpfhub = checker.verificar()

 saude_geral = 'healthy'
 if status_cpfhub['status'] == 'unhealthy':
 saude_geral = 'unhealthy'
 elif status_cpfhub['status'] == 'degraded':
 saude_geral = 'degraded'

 return jsonify({
 'status': saude_geral,
 'dependencias': {
 'cpfhub_api': status_cpfhub
 }
 }), 200 if saude_geral == 'healthy' else 503
```

---

## Integrando com ferramentas de monitoramento

* **Grafana + Prometheus** -- Exportar metricas de latência e disponibilidade.

* **Datadog** -- Health check nativo com alertas configurados.

* **UptimeRobot / Pingdom** -- Monitoramento externo do seu endpoint `/health`.

* **PagerDuty / OpsGenie** -- Alertas para a equipe de plantao quando o status muda para unhealthy.

---

## Definindo thresholds

| Metrica | Healthy | Degraded | Unhealthy |
| --- | --- | --- | --- |
| Latência | < 2s | 2s a 5s | > 5s ou timeout |
| Status HTTP | 200 ou 404 | 500, 503 | Sem resposta |
| Taxa de sucesso | > 99% | 95% a 99% | < 95% |

---

## 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, 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

Health checks automatizados são a linha de defesa entre uma degradacao silenciosa e uma resposta proativa. Monitorar a disponibilidade e a latência da API de CPF garante que você identifique problemas antes dos seus usuários e tome decisões informadas sobre fallbacks e retentativas.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.