# Como medir a latência da API de CPF e otimizar a performance

> Aprenda a medir a latência de uma API de consulta de CPF com técnicas práticas e otimize a performance da sua integração.

**Publicado:** 18/05/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-medir-latencia-api-cpf-otimizar-performance

---


Para medir a latência da API de CPF, use cURL com variáveis de tempo ou bibliotecas como `requests` (Python) e `fetch` (Node.js) para capturar o tempo total de resposta. A API da CPFHub.io tem tempo médio de resposta de aproximadamente 900ms — com connection pooling, cache local e monitoramento por percentis, você extrai o máximo de performance da integração.

## Introdução

A latência de uma API influencia diretamente a experiência do usuário e a eficiência de processos críticos como onboarding, checkout e concessão de crédito. Quando falamos de consultas de CPF, cada milissegundo importa — especialmente em fluxos que exigem validação em tempo real.

---

## O que é latência em APIs REST

Latência é o tempo total entre o envio de uma requisição e o recebimento da resposta completa. Ela inclui:

* **DNS lookup** — Resolução do nome de domínio para IP.

* **TCP handshake** — Estabelecimento da conexão com o servidor.

* **TLS negotiation** — Negociação do certificado SSL/HTTPS.

* **Time to first byte (TTFB)** — Tempo até o primeiro byte da resposta chegar.

* **Transferência de dados** — Tempo para receber o corpo completo da resposta.

A API da CPFHub.io tem tempo médio de resposta de aproximadamente 900ms, mas diversos fatores do lado do cliente podem adicionar latência ao fluxo completo.

---

## Medindo a latência com cURL

A forma mais direta de medir latência é usando cURL com variáveis de tempo:

```bash
curl -X GET https://api.cpfhub.io/cpf/12345678900 \
 -H "x-api-key: SUA_CHAVE_DE_API" \
 -H "Accept: application/json" \
 --max-time 15 \
 -w "\n\nDNS: %{time_namelookup}s\nConexao: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
 -o /dev/null -s
```

A saída será algo como:

```
DNS: 0.028s
Conexao: 0.085s
TLS: 0.192s
TTFB: 0.910s
Total: 0.915s
```

Essa decomposição permite identificar exatamente onde o tempo está sendo consumido.

---

## Medindo a latência em Python

Para medições programáticas, você pode registrar o tempo de cada etapa:

```python
import requests
import time

url = 'https://api.cpfhub.io/cpf/12345678900'
headers = {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
}

inicio = time.perf_counter()
response = requests.get(url, headers=headers, timeout=15)
fim = time.perf_counter()

latencia_ms = (fim - inicio) * 1000

print(f'Status: {response.status_code}')
print(f'Latencia total: {latencia_ms:.2f}ms')

# Detalhamento via response.elapsed (tempo do servidor)
print(f'Tempo do servidor: {response.elapsed.total_seconds() * 1000:.2f}ms')
```

A diferença entre o tempo total e `response.elapsed` revela a latência adicionada pela rede e pelo overhead do cliente.

---

## Medindo a latência em Node.js

```javascript
const inicio = performance.now();

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

const data = await response.json();
const fim = performance.now();

console.log(`Latencia: ${(fim - inicio).toFixed(2)}ms`);
console.log(`Status: ${response.status}`);
```

---

## Percentis e métricas estatísticas

Medir uma única chamada não é suficiente. Para uma análise confiável, colete múltiplas amostras e calcule percentis:

| Métrica | O que significa | Quando usar |
| --- | --- | --- |
| P50 (mediana) | 50% das chamadas ficam abaixo desse valor | Visão geral do desempenho típico |
| P90 | 90% das chamadas ficam abaixo desse valor | Identifica degradações pontuais |
| P95 | 95% das chamadas ficam abaixo desse valor | Parâmetro comum para SLAs |
| P99 | 99% das chamadas ficam abaixo desse valor | Detecta outliers e problemas raros |

```python
import numpy as np
import requests
import time

url = 'https://api.cpfhub.io/cpf/12345678900'
headers = {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
}

latencias = []
for i in range(50):
 inicio = time.perf_counter()
 response = requests.get(url, headers=headers, timeout=15)
 fim = time.perf_counter()
 latencias.append((fim - inicio) * 1000)
 time.sleep(2)

print(f'P50: {np.percentile(latencias, 50):.2f}ms')
print(f'P90: {np.percentile(latencias, 90):.2f}ms')
print(f'P95: {np.percentile(latencias, 95):.2f}ms')
print(f'P99: {np.percentile(latencias, 99):.2f}ms')
print(f'Media: {np.mean(latencias):.2f}ms')
```

---

## Estratégias de otimização

### Reutilização de conexão (connection pooling)

Criar uma nova conexão TCP+TLS a cada requisição adiciona centenas de milissegundos. Reutilize conexões:

```python
import requests

session = requests.Session()
session.headers.update({
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
})

# Todas as chamadas reutilizam a mesma conexao TCP
response = session.get('https://api.cpfhub.io/cpf/12345678900', timeout=15)
```

### Cache local de resultados

Se o mesmo CPF é consultado repetidas vezes em curto intervalo, armazene o resultado temporariamente:

```python
from functools import lru_cache
import requests

session = requests.Session()
session.headers.update({
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
})

@lru_cache(maxsize=256)
def consultar_cpf(cpf: str) -> dict:
 response = session.get(
 f'https://api.cpfhub.io/cpf/{cpf}',
 timeout=15
 )
 return response.json()
```

### Resolução DNS local

Configure um resolver DNS local ou use cache de DNS para evitar lookups repetidos. Em ambientes corporativos, isso pode reduzir 20–50ms por chamada.

### Proximidade geográfica

Se o seu servidor está geograficamente distante da infraestrutura da API, considere executar suas chamadas de um servidor mais próximo. A latência de rede é proporcional à distância física.

---

## Monitoramento contínuo

Não basta medir uma vez. Implemente monitoramento contínuo:

* **Dashboards** — Registre latências em ferramentas como Grafana, Datadog ou CloudWatch.

* **Alertas** — Configure alertas quando o P95 ultrapassar limites aceitáveis.

* **Logs estruturados** — Registre latência, status code e timestamp em cada chamada para análise posterior.

---

## Perguntas frequentes

### Qual é a latência média esperada da API de CPF da CPFHub.io?
A latência média da API da CPFHub.io é de aproximadamente 900ms no tempo total de resposta (TTFB + transferência de dados). Com connection pooling e DNS cacheado, o valor real no cliente costuma ficar entre 950ms e 1.100ms, dependendo da localização do servidor e da qualidade da rede.

### Como identificar se o gargalo de latência está na rede ou no servidor?
Compare o tempo total medido no cliente com `response.elapsed` (Python) ou `x-response-time` nos headers de resposta. Se a diferença for grande, o gargalo está na rede ou no handshake TLS — use connection pooling para resolver. Se os valores forem próximos, o gargalo está no processamento da requisição pelo servidor.

### Vale usar cache local de CPF para reduzir latência?
Sim, com ressalvas. Cache local evita chamadas repetidas para o mesmo CPF no mesmo fluxo, reduzindo latência e consumo de consultas. Use TTL curto (segundos a minutos) para dados de sessão e TTL longo (horas) apenas para dados que raramente mudam. A [Receita Federal](https://www.gov.br/receitafederal) atualiza sua base periodicamente, então cache longo pode retornar dados desatualizados.

### A API da CPFHub.io bloqueia requisições quando o limite do plano é atingido?
Não. A API nunca bloqueia — quando o limite mensal de consultas é atingido, ela continua funcionando normalmente e cobra R$0,15 por consulta adicional. Não há interrupção de serviço nem necessidade de upgrade emergencial.

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

Medir e otimizar a latência da API de CPF é um investimento que impacta diretamente a experiência dos seus usuários e a eficiência dos seus processos. Com técnicas como reutilização de conexão, cache local e monitoramento por percentis, você consegue extrair o máximo de performance da integração.

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