Como garantir que sua API de CPF funcione com alta disponibilidade (SLA 99,9%)

Para operações críticas como onboarding, checkout e KYC, a API de consulta de CPF precisa estar disponível o tempo todo. Alta disponibilidade depende da combinação entre um provedor com SLA sólido e uma camada de resiliência na sua aplicação — com timeouts, retries, circuit breaker e fallback em cache. Sem essas práticas, uma instabilidade pontual pode travar cadastros, bloquear checkouts e comprometer operações de KYC.

O que significa SLA 99,9%

SLA (Service Level Agreement) é o compromisso de disponibilidade do provedor. Cada décimo percentual faz diferença quando se trata de sistemas em produção:

A CPFHub.io opera com SLA de 99,9% nos planos pagos, o que representa menos de 44 minutos de downtime possível por mês. Para sistemas que não podem parar, entender esse número é o primeiro passo para arquitetar uma integração resiliente. Consulte o artigo sobre SLA de API de CPF para ver o que exigir contratualmente do seu provedor.

Boas práticas para alta disponibilidade

1. Implemente timeouts adequados

Nunca faça chamadas sem timeout. Uma API travada pode travar toda a sua aplicação.

import requests

def consultar_cpf(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    try:
    response = requests.get(url, headers=headers, timeout=5)
    response.raise_for_status()
    return response.json()
    except requests.Timeout:
    return {'error': 'Timeout', 'success': False}
    except requests.ConnectionError:
    return {'error': 'Conexao falhou', 'success': False}

2. Implemente retry com backoff exponencial

Falhas temporárias acontecem. Um retry inteligente resolve a maioria delas.

import time

def consultar_com_retry(cpf: str, tentativas: int = 3) -> dict:
    for i in range(tentativas):
    resultado = consultar_cpf(cpf)

    if resultado.get('success') or resultado.get('error') is None:
    return resultado

    # Backoff exponencial: 1s, 2s, 4s
    time.sleep(2 ** i)

    return {'error': 'Maximo de tentativas excedido', 'success': False}

3. Implemente circuit breaker

Se a API estiver fora do ar, pare de enviar requisições por um período para evitar sobrecarga.

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, falhas_max=5, reset_apos=60):
    self.falhas = 0
    self.falhas_max = falhas_max
    self.reset_apos = timedelta(seconds=reset_apos)
    self.aberto_em = None

    def pode_chamar(self) -> bool:
    if self.falhas < self.falhas_max:
    return True
    if datetime.now() - self.aberto_em > self.reset_apos:
    self.falhas = 0
    return True
    return False

    def registrar_falha(self):
    self.falhas += 1
    if self.falhas >= self.falhas_max:
    self.aberto_em = datetime.now()

    def registrar_sucesso(self):
    self.falhas = 0

4. Use cache como fallback

Se a API estiver indisponível, retorne dados do cache (mesmo que não sejam os mais recentes) em vez de falhar completamente.

5. Monitore a disponibilidade

• Configure health checks periódicos.

• Use ferramentas como Grafana, Datadog ou UptimeRobot.

• Configure alertas para latência alta ou erros HTTP 5xx.

6. Tenha um plano de degradação graceful

Defina o que acontece quando a API está fora do ar:

Arquitetura resiliente

[Usuário] → [Sua Aplicação] → [Cache Local]
    ↓ (cache miss)
    [Circuit Breaker]
    ↓ (circuito fechado)
    [API CPFHub.io]
    ↓ (retry com backoff)
    [Resposta / Fallback]

Perguntas frequentes

O SLA de 99,9% garante que a API nunca vai falhar?

Não. Um SLA de 99,9% garante disponibilidade de pelo menos 99,9% do tempo, o que ainda permite até 43 minutos de downtime por mês. Por isso a integração precisa ter circuit breaker, retry e fallback em cache — para que sua aplicação funcione mesmo durante esses períodos.

O que acontece se eu exceder o limite de consultas do meu plano?

A API da CPFHub.io não bloqueia requisições quando o limite do plano é atingido. Cada consulta além da cota mensal é cobrada a R$0,15. Isso evita que sistemas em produção parem por causa de um pico de volume inesperado.

Como monitorar a saúde da integração com a API de CPF em produção?

Configure alertas para latência acima de 2 segundos e taxas de erro acima de 1%. Ferramentas como Datadog, Grafana ou o próprio UptimeRobot permitem criar health checks automáticos que disparam notificações antes que o problema afete os usuários finais.

Qual o impacto de uma indisponibilidade da API de CPF em fluxos de KYC?

Em fluxos de KYC, uma indisponibilidade sem plano de contingência pode bloquear completamente o onboarding de novos clientes. A recomendação é enfileirar as solicitações para processamento posterior — assim o usuário avança no cadastro e a validação é concluída assim que a API voltar a responder.

Conclusão

Alta disponibilidade na integração com API de CPF depende de duas coisas: um provedor confiável e uma integração resiliente. Timeouts, retries, circuit breaker e cache não são opcionais em sistemas de produção — são a diferença entre uma indisponibilidade transparente para o usuário e um incidente que bloqueia operações críticas.

A CPFHub.io foi projetada para ser o componente mais estável da sua stack de validação de identidade, com SLA de 99,9% nos planos pagos e latência média de ~900ms. Mas a responsabilidade pela resiliência da integração é compartilhada: use as práticas deste artigo para garantir que o seu sistema se recupere com elegância de qualquer instabilidade.

Cadastre-se em cpfhub.io e comece com 50 consultas gratuitas. Sem cartão de crédito.