# API de CPF: como funciona o SLA e o que acontece quando e violado > Entenda como funciona o SLA de APIs de consulta de CPF, o que os diferentes niveis significam e como se preparar para violacoes. **Publicado:** 04/02/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-cpf-como-funciona-sla-o-que-acontece-quando-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. | SLA | Downtime máximo/mês | Downtime máximo/ano | | --- | --- | --- | | 80% | ~146 horas | ~73 dias | | 95% | ~36 horas | ~18 dias | | 99% | ~7,3 horas | ~3,65 dias | | 99,9% | ~43 minutos | ~8,76 horas | | 99,99% | ~4,3 minutos | ~52,6 minutos | --- ## SLAs da CPFHub.io por plano | Plano | SLA | Preço | Consultas/mês | | --- | --- | --- | --- | | Gratuito | 80% | R$ 0 | 50 | | Pro | 99% | R$ 149/mês | 1.000 | | Corporativo | 99,9% | Sob consulta | Personalizado | ### 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: ```python 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: ```python 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: ```python 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: | Cenário | Comportamento com API | Comportamento sem API | | --- | --- | --- | | Onboarding | Validação em tempo real | Aceitar provisoriamente, revalidar depois | | Checkout | Bloquear se CPF inválido | Prosseguir com validação pendente | | Análise de crédito | Score completo | Score parcial com flag de verificação pendente | --- ## 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 | Sua necessidade | Plano recomendado | | --- | --- | | Testes e desenvolvimento | Gratuito (SLA 80%) | | Produção com fallbacks robustos | Pro (SLA 99%) | | Operações críticas sem margem | Corporativo (SLA 99,9%) | 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](https://www.gov.br/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. ### Leia também - [SLA de API de CPF: níveis de disponibilidade e como escolher](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como funcionam os planos gratuitos das APIs de consulta de CPF](https://cpfhub.io/blog/como-funcionam-os-planos-gratuitos-das-apis-de-consulta-de-cpf) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [O que considerar antes de escolher uma API de CPF gratuita](https://cpfhub.io/blog/o-que-considerar-antes-de-escolher-uma-api-de-cpf-gratuita) --- ## 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](https://www.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.