# Como fazer a transição de uma API de CPF gratuita para uma API premium > Guia completo para migrar de uma API gratuita de CPF para uma versão premium sem interrupção. Estratégias de transição gradual e validação. **Publicado:** 04/02/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/transicao-api-cpf-gratuita-premium --- A transição de uma API de CPF gratuita para premium envolve três etapas principais: inventariar todos os pontos de integração, ativar a nova chave com feature flag para migração gradual e validar paridade de resposta antes de desligar o plano antigo. Com esse processo, a migração acontece sem downtime e com rollback instantâneo disponível a qualquer momento. ## Introdução A transição de uma API gratuita para uma versão premium é um marco positivo para qualquer negócio: significa que o volume cresceu, a validação de CPF se tornou crítica e o retorno sobre o investimento justifica o custo. No entanto, essa migração precisa ser executada com cuidado para evitar interrupções no serviço, inconsistências de dados e surpresas nos custos. Este guia mostra como migrar para a [**CPFHub.io**](https://www.cpfhub.io/) de forma segura, gradual e validada. --- ## Planejamento pré-migração Antes de iniciar qualquer mudança técnica, é essencial mapear o cenário atual e definir os objetivos da migração. | Item | Ação | Responsável | |------|------|-------------| | Inventário de integração | Listar todos os pontos que usam a API | Equipe técnica | | Volume atual | Medir requisições diárias e mensais | DevOps | | Tratamento de erros | Verificar como erros são tratados hoje | Equipe técnica | | Configuração da API key | Identificar onde a key está armazenada | DevOps/Segurança | | Testes existentes | Verificar cobertura de testes da integração | QA | | Budget aprovado | Confirmar orçamento para o plano premium | Gestão | ```python import os import json class InventarioIntegracao: def __init__(self): self.pontos_integracao = [] def registrar(self, servico: str, arquivo: str, tipo: str): self.pontos_integracao.append({ "servico": servico, "arquivo": arquivo, "tipo": tipo, "usa_variavel_ambiente": True, "tem_fallback": False, "tem_testes": False }) def gerar_checklist(self) -> dict: total = len(self.pontos_integracao) com_env = sum(1 for p in self.pontos_integracao if p["usa_variavel_ambiente"]) com_fallback = sum(1 for p in self.pontos_integracao if p["tem_fallback"]) com_testes = sum(1 for p in self.pontos_integracao if p["tem_testes"]) return { "total_pontos": total, "usando_variavel_ambiente": f"{com_env}/{total}", "com_fallback": f"{com_fallback}/{total}", "com_testes": f"{com_testes}/{total}", "pronto_para_migrar": com_env == total, "pontos": self.pontos_integracao } # Levantamento inventario = InventarioIntegracao() inventario.registrar("API de cadastro", "services/cpf_service.py", "backend") inventario.registrar("Validação no checkout", "services/checkout.py", "backend") inventario.registrar("Importação CSV", "jobs/importar_clientes.py", "batch") print(json.dumps(inventario.gerar_checklist(), indent=2)) ``` - **Inventário completo** -- cada ponto de integração precisa ser migrado individualmente - **Variável de ambiente** -- se a key está hardcoded em algum lugar, corrija antes da migração - **Cobertura de testes** -- testes existentes validarão automaticamente se a migração manteve a funcionalidade --- ## Estratégia de migração com feature flag A migração mais segura utiliza feature flags para controlar qual versão da API cada serviço utiliza. ```python import os import requests from enum import Enum class APITier(Enum): GRATUITO = "gratuito" PREMIUM = "premium" class CPFServiceMigravel: def __init__(self): self.configs = { APITier.GRATUITO: { "api_key": os.environ.get("CPFHUB_API_KEY_FREE", ""), "base_url": "https://api.cpfhub.io/cpf", }, APITier.PREMIUM: { "api_key": os.environ.get("CPFHUB_API_KEY_PREMIUM", ""), "base_url": "https://api.cpfhub.io/cpf", } } tier_str = os.environ.get("CPFHUB_TIER", "gratuito") self.tier_ativo = APITier(tier_str) self.session = requests.Session() def consultar(self, cpf: str) -> dict: config = self.configs[self.tier_ativo] cpf_limpo = "".join(c for c in cpf if c.isdigit()) response = self.session.get( f"{config['base_url']}/{cpf_limpo}", headers={"x-api-key": config["api_key"]}, timeout=10 ) response.raise_for_status() resultado = response.json() resultado["_tier"] = self.tier_ativo.value return resultado def alternar_tier(self, novo_tier: APITier): self.tier_ativo = novo_tier # Migração controlada por variável de ambiente: # CPFHUB_TIER=gratuito (padrão) # CPFHUB_TIER=premium (após migração) ``` ```python # Shadow mode: comparar respostas entre gratuito e premium class ShadowComparator: def __init__(self): self.service_free = CPFServiceMigravel() self.service_free.tier_ativo = APITier.GRATUITO self.service_premium = CPFServiceMigravel() self.service_premium.tier_ativo = APITier.PREMIUM self.divergencias = [] def comparar(self, cpf: str) -> dict: resultado_free = self.service_free.consultar(cpf) resultado_premium = self.service_premium.consultar(cpf) campos_comparar = ["cpf", "name", "birthDate", "gender"] iguais = True for campo in campos_comparar: val_free = resultado_free.get("data", {}).get(campo) val_premium = resultado_premium.get("data", {}).get(campo) if val_free != val_premium: iguais = False self.divergencias.append({ "cpf": cpf, "campo": campo, "free": val_free, "premium": val_premium }) return { "cpf": cpf, "paridade": iguais, "divergencias": len(self.divergencias) } ``` | Fase | CPFHUB_TIER | Comportamento | |------|-------------|---------------| | 1. Preparação | gratuito | Tudo funciona como antes | | 2. Shadow test | gratuito + premium em paralelo | Comparar respostas | | 3. Canary | premium (10% do tráfego) | Validar em produção | | 4. Migração | premium | 100% no premium | | 5. Limpeza | premium | Remover código do gratuito | - **Feature flag** -- a variável CPFHUB_TIER controla qual API key é usada sem deploy de código - **Shadow mode** -- envia para ambas as APIs e compara, garantindo paridade antes da migração - **Rollback instantâneo** -- basta alterar a variável de ambiente para voltar ao gratuito --- ## Validação pós-migração Após a migração, valide que tudo funciona corretamente e monitore as métricas de perto. ```python class ValidacaoPosMigracao: def __init__(self, service: CPFServiceMigravel): self.service = service self.resultados = [] def executar_suite(self, cpfs_teste: list) -> dict: for cpf in cpfs_teste: try: resultado = self.service.consultar(cpf) self.resultados.append({ "cpf": cpf, "sucesso": resultado.get("success", False), "tier": resultado.get("_tier"), "status": "ok" }) except Exception as e: self.resultados.append({ "cpf": cpf, "sucesso": False, "tier": self.service.tier_ativo.value, "status": f"erro: {str(e)}" }) total = len(self.resultados) sucessos = sum(1 for r in self.resultados if r["sucesso"]) return { "total_testes": total, "sucessos": sucessos, "falhas": total - sucessos, "taxa_sucesso": f"{sucessos/total*100:.1f}%", "tier_ativo": self.service.tier_ativo.value, "pronto_para_producao": sucessos == total } # Executar validação service = CPFServiceMigravel() validador = ValidacaoPosMigracao(service) resultado = validador.executar_suite([ "12345678909", "98765432100", "11122233344", ]) print(json.dumps(resultado, indent=2)) ``` | Verificação | Critério de sucesso | Ação se falhar | |------------|-------------------|----------------| | Todos os CPFs de teste retornam dados | 100% de sucesso | Verificar API key | | Latência igual ou menor que gratuito | p99 < latência anterior | Investigar rede | | Campos retornados são os mesmos | Paridade 100% | Reportar divergência | | Sem erros 401 ou 403 | Zero erros de autenticação | Verificar permissões | | Consumo extra faturado corretamente | R$0,15/consulta excedente | Conferir fatura em app.cpfhub.io/settings/billing | - **Suite de testes** -- execute com CPFs conhecidos para validar a integração - **Comparação de latência** -- a versão premium deve ter latência igual ou melhor - **Monitoramento intensivo** -- nas primeiras 48h após migração, acompanhe métricas de perto --- ## Otimizando o uso do plano premium Após a migração, otimize o consumo para extrair o máximo valor do investimento. ```python class OtimizadorConsumo: def __init__(self, limite_mensal: int, custo_mensal: float): self.limite = limite_mensal self.custo = custo_mensal self.consumo_diario = [] def registrar_dia(self, requisicoes: int): self.consumo_diario.append(requisicoes) def projecao_mensal(self) -> dict: if not self.consumo_diario: return {"erro": "Sem dados"} media_diaria = sum(self.consumo_diario) / len(self.consumo_diario) projecao = media_diaria * 30 utilizacao = (projecao / self.limite) * 100 custo_por_req = self.custo / max(projecao, 1) return { "media_diaria": round(media_diaria), "projecao_mensal": round(projecao), "limite_mensal": self.limite, "utilizacao": f"{utilizacao:.1f}%", "custo_por_requisicao": f"R$ {custo_por_req:.4f}", "alerta": "sub-utilizado" if utilizacao < 30 else "adequado" if utilizacao < 80 else "próximo do limite" } ``` - **Sub-utilização** -- se está usando menos de 30% do plano, talvez um plano menor seja melhor - **Custo por requisição** -- métrica que permite comparar o valor real do serviço - **Projeção** -- acompanhe a tendência para antecipar necessidade de upgrade --- ## Perguntas frequentes ### Quando é o momento certo para migrar do plano gratuito para o pago? O sinal mais claro é quando as 50 consultas mensais do plano gratuito não cobrem mais o volume real de uso — ou quando você está prestes a colocar a integração em produção. O plano Pro (R$149/mês, 1.000 consultas) oferece SLA de 99% e suporte via WhatsApp, adequados para aplicações em produção. ### A migração de chave de API causa downtime? Não, se bem planejada. A abordagem recomendada é usar feature flags controladas por variável de ambiente: a antiga chave continua ativa enquanto a nova é testada em shadow mode. O rollback é instantâneo — basta alterar a variável de ambiente sem nenhum redeploy. ### O que acontece se o volume ultrapassar o limite do plano Pro após a migração? A API não bloqueia nem retorna erro. Ao ultrapassar 1.000 consultas mensais, cada consulta adicional é cobrada automaticamente a R$0,15 — o serviço continua respondendo normalmente. Você pode acompanhar o consumo em tempo real em `app.cpfhub.io/settings/billing`. ### Como garantir conformidade com a LGPD durante a migração de API? Mantenha os logs de auditoria das consultas durante e após a migração, assegurando rastreabilidade do tratamento de dados pessoais. A [ANPD](https://www.gov.br/anpd) orienta que alterações em sistemas que tratam dados pessoais sejam documentadas, com base legal mantida intacta no processo de transição. ### Leia também - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Quando migrar da API gratuita para a versão paga](https://cpfhub.io/blog/quando-migrar-api-gratuita-versao-paga) - [API de consulta de CPF: diferenças entre planos gratuito, Pro e Corporate](https://cpfhub.io/blog/api-de-consulta-de-cpf-diferencas-entre-planos-gratuito-pro-e-corporate) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) --- ## Conclusão A transição de uma API gratuita para premium é um processo que requer planejamento, execução gradual e validação rigorosa. Com inventário completo dos pontos de integração, feature flags para controle granular, shadow mode para validação de paridade e monitoramento intensivo pós-migração, você garante uma transição sem interrupções. O resultado é uma integração mais confiável, com maior capacidade e suporte dedicado. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e migre para o Pro quando o volume crescer, mantendo a mesma API e a mesma estrutura de resposta sem nenhuma alteração de código.