# Como migrar dados e configurações ao fazer upgrade de uma API gratuita para paga > Guia passo a passo para migrar de uma API gratuita para uma paga de CPF sem interrupções. Aprenda a preservar dados e configurações. **Publicado:** 18/03/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/migrar-dados-configuracoes-upgrade-api-gratuita-paga --- Migrar de uma API gratuita de CPF para um plano pago exige trocar a chave de autenticação, validar que as respostas são idênticas entre os planos e fazer rollout gradual — tudo sem alterar o endpoint ou a estrutura de dados. Na CPFHub.io, o endpoint permanece `GET https://api.cpfhub.io/cpf/{CPF}` em ambos os planos, o que torna a migração técnica simples e sem risco de regressão. ## Introdução O momento do upgrade de uma API gratuita para uma paga é um marco importante no crescimento de qualquer produto. Quando mal executada, essa migração pode causar downtime, perda de dados e retrabalho significativo. Boas práticas de engenharia de software — como as documentadas pelo [NIST](https://csrc.nist.gov/publications/detail/sp/800-204b/final) para sistemas de API seguras — recomendam migrar credenciais de forma gradual, com validação em cada etapa antes de avançar. --- ## Planejamento da migração Antes de iniciar qualquer alteração, mapeie todos os componentes que dependem da API: - **Endpoints consumidos** -- liste todas as rotas da API utilizadas pela aplicação - **Chaves de autenticação** -- identifique onde as chaves estão armazenadas (variáveis de ambiente, secrets managers, hardcoded) - **Formato de resposta** -- documente a estrutura esperada das respostas para detectar diferenças - **Tratamento de erros** -- mapeie como a aplicação lida com cada código de status HTTP - **Dependências downstream** -- identifique serviços internos que dependem dos dados retornados pela API --- ## Checklist de migração passo a passo Siga esta sequência para uma migração sem surpresas: | Etapa | Ação | Verificação | |---|---|---| | 1 | Obter credenciais do plano pago | Chave funciona em sandbox | | 2 | Configurar chave em variáveis de ambiente | Variável acessível no deploy | | 3 | Testar endpoints em ambiente de dev | Respostas idênticas ao gratuito | | 4 | Atualizar limites de volume no código | Novos limites configurados | | 5 | Executar testes de integração | Todos passando | | 6 | Deploy em staging | Validação completa do fluxo | | 7 | Canary release (10% do tráfego) | Métricas estáveis | | 8 | Rollout completo (100%) | Monitoramento ativo | | 9 | Desativar chave gratuita | Sem tráfego residual | | 10 | Documentar a migração | Runbook atualizado | --- ## Script de migração automatizada com Python Automatize a validação da migração comparando respostas entre os dois planos: ```python import requests import json from datetime import datetime class MigrationValidator: def __init__(self, chave_gratuita: str, chave_paga: str): self.chave_gratuita = chave_gratuita self.chave_paga = chave_paga self.base_url = "https://api.cpfhub.io/cpf" self.resultados = [] def consultar(self, cpf: str, chave: str) -> dict: response = requests.get( f"{self.base_url}/{cpf}", headers={"x-api-key": chave}, timeout=10 ) return { "status": response.status_code, "latencia_ms": response.elapsed.total_seconds() * 1000, "body": response.json() } def comparar_respostas(self, cpf: str) -> dict: resp_gratis = self.consultar(cpf, self.chave_gratuita) resp_paga = self.consultar(cpf, self.chave_paga) comparacao = { "cpf": cpf, "timestamp": datetime.now().isoformat(), "status_igual": resp_gratis["status"] == resp_paga["status"], "dados_iguais": resp_gratis["body"] == resp_paga["body"], "latencia_gratis": f"{resp_gratis['latencia_ms']:.0f}ms", "latencia_paga": f"{resp_paga['latencia_ms']:.0f}ms" } self.resultados.append(comparacao) return comparacao def executar_validacao(self, cpfs: list) -> dict: print("Validando migração...\n") for cpf in cpfs: resultado = self.comparar_respostas(cpf) status = "OK" if resultado["dados_iguais"] else "DIVERGENTE" print(f"[{status}] CPF {cpf[:3]}...: " f"grátis={resultado['latencia_gratis']} " f"paga={resultado['latencia_paga']}") total = len(self.resultados) iguais = sum(1 for r in self.resultados if r["dados_iguais"]) resumo = { "total_testados": total, "respostas_identicas": iguais, "taxa_compatibilidade": f"{(iguais/total)*100:.1f}%", "migração_segura": iguais == total } print(f"\nResumo: {resumo['taxa_compatibilidade']} compatível") print(f"Migração segura: {'SIM' if resumo['migração_segura'] else 'NÃO'}") return resumo # Execução validator = MigrationValidator("CHAVE_GRATUITA", "CHAVE_PAGA") validator.executar_validacao(["12345678909", "98765432100", "11122233344"]) ``` --- ## Gerenciando a transição de chaves A troca de chaves de API é o momento mais delicado da migração. Estratégias para minimizar riscos: - **Feature flag** -- utilize uma flag para alternar entre chaves sem necessidade de deploy - **Variáveis de ambiente** -- nunca hardcode chaves; use env vars que podem ser alteradas em runtime - **Rollback preparado** -- mantenha a chave gratuita ativa por pelo menos 48h após a migração completa - **Rotação gradual** -- em sistemas distribuídos, atualize instância por instância monitorando métricas - **Secrets manager** -- utilize AWS Secrets Manager, HashiCorp Vault ou similar para centralizar a gestão de chaves --- ## Validando a migração em produção Após o deploy, monitore estas métricas nas primeiras 48 horas: - **Taxa de sucesso das consultas** -- deve se manter acima de 99% - **Latência média e P99** -- compare com a baseline do plano gratuito - **Volume de consultas** -- confirme que o tráfego migrou completamente para a nova chave - **Erros de autenticação** -- monitore erros 401/403 que indicam problemas com a nova chave - **Consumo de cota** -- verifique no painel `app.cpfhub.io/settings/billing` se o volume está dentro do plano Pro (1.000 consultas/mês por R$149). Consultas extras são cobradas automaticamente a R$0,15 cada, sem bloqueio. --- ## Perguntas frequentes ### O endpoint e o formato de resposta mudam ao migrar para o plano pago? Não. O endpoint permanece `GET https://api.cpfhub.io/cpf/{CPF}` e a estrutura de resposta é idêntica entre os planos gratuito e Pro. A única mudança técnica é a chave de autenticação no header `x-api-key`. Isso significa que o código do protótipo ou MVP vai direto para produção sem alteração de lógica. ### O que acontece se eu ultrapassar o limite de 1.000 consultas do plano Pro durante a migração? A API não bloqueia as consultas. Cada chamada além do limite do plano é cobrada automaticamente a R$0,15. Isso garante que picos de tráfego durante a validação pós-migração não interrompam o serviço. Acompanhe o consumo em `app.cpfhub.io/settings/billing` para antecipar custos. ### Por quanto tempo devo manter a chave gratuita ativa após a migração? Recomenda-se manter a chave gratuita ativa por pelo menos 48 horas após o rollout completo para produção. Esse período permite identificar tráfego residual de instâncias que não foram atualizadas (comum em sistemas distribuídos) e garantir rollback sem downtime caso algo inesperado ocorra. ### Como validar que as respostas são idênticas entre o plano gratuito e o pago antes do cutover? Use o script de validação incluído neste artigo: ele consulta o mesmo CPF com as duas chaves em paralelo e compara os payloads JSON. Uma taxa de compatibilidade de 100% confirma que a migração não introduz regressões. Execute o script com pelo menos 10 CPFs diferentes para cobrir variações nos dados retornados. ### Leia também - [SLA de API de CPF: níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Quando migrar de API gratuita para versão paga](https://cpfhub.io/blog/quando-migrar-api-gratuita-versao-paga) - [APIs gratuitas de CPF para prototipagem rápida de produtos digitais](https://cpfhub.io/blog/apis-gratuitas-cpf-prototipagem-rapida-produtos-digitais) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) --- ## Conclusão A migração de uma API gratuita para paga é uma operação que exige planejamento, testes e monitoramento cuidadoso. Com o script de validação, o checklist de migração e as estratégias de gerenciamento de chaves apresentados neste guia, o processo se torna previsível e seguro. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a integração hoje para que o upgrade para o plano Pro, quando chegar a hora, seja apenas uma troca de chave.