Como medir a latência da API de CPF e otimizar a 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:

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:

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

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:

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:

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:

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

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 — 50 consultas mensais gratuitas, sem cartão de crédito.