API de CPF: como funciona o SLA e o que acontece quando e violado

O SLA (Service Level Agreement) de uma API de CPF define o percentual mínimo de disponibilidade que o provedor garante por mês. Na CPFHub.io, o plano gratuito tem SLA de 80%, o Pro tem 99% e o Corporativo, 99,9% — e entender essa diferença é decisivo para escolher o plano certo para cada contexto de uso.

Introdução

Quando você integra uma API de CPF em processos críticos como onboarding, checkout ou concessão de crédito, a disponibilidade da API deixa de ser uma métrica técnica e passa a ser um fator de negócio. O SLA é o compromisso formal do provedor sobre essa disponibilidade, e entendê-lo é essencial para tomar decisões arquiteturais informadas.

O que é SLA

SLA (Service Level Agreement) é um acordo formal que define o nível mínimo de disponibilidade que o provedor se compromete a manter. É expresso como uma porcentagem de uptime em um período, normalmente mensal.

SLAs da CPFHub.io por plano

O que cada nível significa

• 80% (Gratuito) -- Adequado para testes, desenvolvimento e validação de conceito. Espere indisponibilidades ocasionais.

• 99% (Pro) -- Adequado para produção com processos que toleram breves interrupções. Máximo de ~7 horas de downtime por mês.

• 99,9% (Corporativo) -- Para operações críticas onde cada minuto de indisponibilidade tem impacto financeiro. Máximo de ~43 minutos de downtime por mês.

O que acontece quando o SLA é violado

Quando um provedor não cumpre o SLA acordado, as consequências típicas incluem:

• Créditos de serviço -- Compensação proporcional ao tempo de indisponibilidade.

• Extensão de plano -- Dias adicionais de serviço sem custo.

• Suporte prioritário -- Atendimento acelerado para resolução do problema.

A CPFHub.io conta com monitoramento 24/7 e uptime histórico de 99,9%, demonstrando compromisso com a disponibilidade.

Como medir se o SLA está sendo cumprido

Não dependa apenas do provedor para medir o SLA. Implemente seu próprio monitoramento:

import requests
import time
from datetime import datetime, timedelta
import json

class MonitorSLA:
    def __init__(self, api_key, redis_client):
    self.api_key = api_key
    self.redis = redis_client

    def verificar_disponibilidade(self):
    inicio = time.perf_counter()
    disponivel = False
    latencia_ms = 0

    try:
    response = requests.get(
    'https://api.cpfhub.io/cpf/00000000000',
    headers={
    'x-api-key': self.api_key,
    'Accept': 'application/json'
    },
    timeout=15
    )
    latencia_ms = (time.perf_counter() - inicio) * 1000
    # Considerar disponivel se responder (200 ou 404)
    disponivel = response.status_code in [200, 404]
    except Exception:
    latencia_ms = (time.perf_counter() - inicio) * 1000

    # Registrar
    agora = datetime.utcnow()
    registro = {
    'timestamp': agora.isoformat(),
    'disponivel': disponivel,
    'latencia_ms': round(latencia_ms, 2)
    }

    chave = f'sla:check:{agora.strftime("%Y-%m")}'
    self.redis.rpush(chave, json.dumps(registro))
    self.redis.expire(chave, 35 * 86400)

    return registro

    def calcular_sla_mensal(self, mes=None):
    if mes is None:
    mes = datetime.utcnow().strftime('%Y-%m')

    chave = f'sla:check:{mes}'
    registros = [json.loads(r) for r in self.redis.lrange(chave, 0, -1)]

    if not registros:
    return {'sla': None, 'mensagem': 'Sem dados para o periodo'}

    total = len(registros)
    disponiveis = sum(1 for r in registros if r['disponivel'])
    sla_percentual = (disponiveis / total) * 100

    return {
    'mes': mes,
    'total_verificacoes': total,
    'disponiveis': disponiveis,
    'indisponiveis': total - disponiveis,
    'sla_percentual': round(sla_percentual, 3),
    'dentro_do_sla': sla_percentual >= 99.0 # ajustar conforme plano
    }

Preparando sua aplicação para violações de SLA

Fallback local

Mantenha um cache dos últimos resultados para servir quando a API estiver indisponível:

def consultar_cpf_com_fallback(cpf, session, redis_client):
    cache_key = f'cpf:cache:{cpf}'

    try:
    response = session.get(
    f'https://api.cpfhub.io/cpf/{cpf}',
    timeout=10
    )
    if response.status_code == 200:
    data = response.json()
    # Cachear por 24 horas
    redis_client.setex(cache_key, 86400, json.dumps(data))
    return {'fonte': 'api', 'data': data}
    except Exception:
    pass

    # Fallback: usar cache
    cached = redis_client.get(cache_key)
    if cached:
    return {'fonte': 'cache', 'data': json.loads(cached)}

    return {'fonte': 'indisponivel', 'data': None}

Circuit breaker

Evite sobrecarregar uma API que já está com problemas:

class CircuitBreaker:
    def __init__(self, limite_falhas=5, tempo_reset=60):
    self.falhas = 0
    self.limite = limite_falhas
    self.tempo_reset = tempo_reset
    self.aberto_em = None

    @property
    def aberto(self):
    if self.falhas >= self.limite:
    if self.aberto_em is None:
    self.aberto_em = time.time()
    # Verificar se já passou o tempo de reset
    if time.time() - self.aberto_em > self.tempo_reset:
    self.falhas = 0
    self.aberto_em = None
    return False
    return True
    return False

    def registrar_sucesso(self):
    self.falhas = 0
    self.aberto_em = None

    def registrar_falha(self):
    self.falhas += 1

breaker = CircuitBreaker(limite_falhas=5, tempo_reset=60)

def consultar_com_circuit_breaker(cpf, session):
    if breaker.aberto:
    return {'erro': 'circuit_breaker_aberto', 'usar_fallback': True}

    try:
    response = session.get(
    f'https://api.cpfhub.io/cpf/{cpf}',
    headers={
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    timeout=15
    )
    if response.status_code in [500, 502, 503]:
    breaker.registrar_falha()
    return {'erro': f'http_{response.status_code}', 'usar_fallback': True}

    breaker.registrar_sucesso()
    return response.json()
    except Exception:
    breaker.registrar_falha()
    return {'erro': 'timeout_ou_rede', 'usar_fallback': True}

Degradação graceful

Quando a API estiver indisponível, sua aplicação deve degradar de forma controlada:

Alertas de SLA

Configure alertas quando o SLA estiver próximo de ser violado:

• Alerta 1 -- 3 falhas consecutivas nas verificações de disponibilidade.

• Alerta 2 -- SLA abaixo de 99,5% nas últimas 24 horas.

• Alerta 3 -- SLA abaixo de 99% no mês corrente.

Escolhendo o plano pelo SLA

O custo de indisponibilidade no seu negócio deve guiar a escolha. Se cada hora de downtime custa mais do que a diferença entre planos, o upgrade se paga sozinho.

Perguntas frequentes

Qual é a diferença prática entre SLA de 99% e 99,9% para uma API de CPF?

Com SLA de 99%, o provedor pode ficar indisponível até ~7,3 horas por mês — aceitável para processos que toleram breves interrupções com fallback configurado. Com SLA de 99,9%, o downtime máximo é ~43 minutos por mês, indicado para operações críticas onde cada minuto de indisponibilidade representa perda financeira direta, como onboarding de crédito em tempo real.

O que o provedor deve compensar quando viola o SLA?

As práticas mais comuns incluem créditos de serviço proporcionais ao tempo de indisponibilidade, extensão do plano sem custo e suporte prioritário para resolução. Verifique os termos de serviço do provedor antes de contratar — a compensação varia entre fornecedores e nem sempre cobre prejuízos indiretos.

Como implementar monitoramento independente do SLA da API de CPF?

Configure verificações periódicas (a cada 5 minutos, por exemplo) que fazem uma chamada de teste à API e registram disponibilidade e latência. Armazene os resultados em Redis ou banco de dados e calcule o percentual de uptime mensal. Isso permite contestar violações de SLA com dados próprios, sem depender do dashboard do provedor.

A LGPD impõe requisitos sobre disponibilidade de APIs que tratam dados pessoais?

A ANPD não define SLAs mínimos, mas exige que o controlador adote medidas técnicas adequadas para proteger dados pessoais — o que inclui garantir a continuidade dos processos que dependem desses dados. Uma API com SLA insuficiente para o contexto de uso pode ser considerada uma medida técnica inadequada em caso de incidente.

Conclusão

Entender o SLA da sua API de CPF é fundamental para projetar uma integração resiliente. Com monitoramento próprio, circuit breakers, fallbacks e degradação graceful, sua aplicação se mantém funcional mesmo quando o SLA é temporariamente violado. Ao escolher o plano adequado, você alinha expectativas de disponibilidade com as necessidades reais do negócio — evitando tanto superdimensionamento de custo quanto indisponibilidades que impactam o usuário final.

Cadastre-se em cpfhub.io e comece com 50 consultas gratuitas por mês, sem cartão de crédito. Para produção com SLA garantido de 99%, o plano Pro está disponível por R$149/mês.