# Como implementar feature flags para rollout gradual de integrações com API de CPF

> Aprenda a usar feature flags para fazer rollout gradual de integrações com API de CPF, reduzindo riscos e controlando o lançamento.

**Publicado:** 18/02/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/implementar-feature-flags-rollout-gradual-integracoes-api-cpf

---


Feature flags permitem ativar a integração com a API de CPF para uma parcela controlada dos usuários, expandindo progressivamente conforme os resultados se confirmam. Com essa abordagem, você elimina o risco de lançar para 100% da base de uma vez e ainda ganha a capacidade de reverter em segundos caso algo saia do esperado.

## Introdução

Lançar uma nova integração com API de CPF para 100% dos usuários de uma vez é arriscado. Se houver um bug, um problema de performance ou um consumo de cota inesperado, o impacto atinge todos os clientes simultaneamente. Feature flags permitem fazer um rollout gradual — ativando a integração para uma parcela dos usuários, monitorando os resultados e expandindo progressivamente. O OWASP recomenda esse tipo de controle de liberação gradual como parte das boas práticas de desenvolvimento seguro de software: [owasp.org](https://owasp.org/www-project-developer-guide/).

## O que são feature flags

Feature flags (ou feature toggles) são mecanismos que permitem ativar ou desativar funcionalidades em produção sem precisar fazer deploy. No contexto de uma integração com API de CPF, eles permitem:

* **Rollout gradual** — Ativar para 5%, 20%, 50%, 100% dos usuários.

* **Rollback instantâneo** — Desativar a integração em segundos se algo der errado.

* **Testes A/B** — Comparar o fluxo com e sem validação de CPF.

* **Segmentação** — Ativar apenas para clientes corporativos ou regiões específicas.

---

## Implementação básica de feature flags

### Feature flag simples com Redis

```python
import redis
import random

r = redis.Redis(host='localhost', port=6379, db=0)

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

 def esta_ativo(self, flag_name, user_id=None, percentual=None):
 """Verifica se uma feature flag esta ativa."""
 # Verificar flag global (ativo/inativo)
 status = self.redis.get(f'flag:{flag_name}:status')
 if status == b'disabled':
 return False
 if status == b'enabled':
 return True

 # Rollout por percentual
 if percentual is None:
 percentual_str = self.redis.get(f'flag:{flag_name}:percentual')
 percentual = int(percentual_str) if percentual_str else 0

 if user_id:
 # Hash determinístico para consistência por usuário
 hash_val = hash(f'{flag_name}:{user_id}') % 100
 return hash_val < percentual
 else:
 return random.randint(0, 99) < percentual

 def definir_percentual(self, flag_name, percentual):
 self.redis.set(f'flag:{flag_name}:percentual', percentual)
 self.redis.set(f'flag:{flag_name}:status', 'rollout')

 def ativar(self, flag_name):
 self.redis.set(f'flag:{flag_name}:status', 'enabled')

 def desativar(self, flag_name):
 self.redis.set(f'flag:{flag_name}:status', 'disabled')

flags = FeatureFlags(r)
```

---

## Aplicando feature flags na integração com API de CPF

### No fluxo de onboarding

```python
import requests

class ServicoOnboarding:
 def __init__(self, api_key, flags):
 self.api_key = api_key
 self.flags = flags
 self.session = requests.Session()
 self.session.headers.update({
 'x-api-key': api_key,
 'Accept': 'application/json'
 })

 def processar_cadastro(self, user_id, cpf, nome):
 resultado = {'cpf': cpf, 'nome': nome, 'validacao_api': None}

 # Verificar se a validação via API está ativa para este usuário
 if self.flags.esta_ativo('validacao_cpf_api', user_id=user_id):
 validacao = self._validar_via_api(cpf, nome)
 resultado['validacao_api'] = validacao

 if not validacao['aprovado']:
 resultado['status'] = 'pendente_revisao'
 return resultado

 # Validação sintática (sempre executa)
 if not self._validar_sintaxe_cpf(cpf):
 resultado['status'] = 'cpf_invalido'
 return resultado

 resultado['status'] = 'aprovado'
 return resultado

 def _validar_via_api(self, cpf, nome):
 try:
 response = self.session.get(
 f'https://api.cpfhub.io/cpf/{cpf}',
 timeout=15
 )
 if response.status_code == 200:
 data = response.json()
 if data.get('success'):
 nome_api = data['data']['name'].upper()
 nome_informado = nome.upper()
 match = nome_api.split()[0] == nome_informado.split()[0]
 return {'aprovado': match, 'fonte': 'api', 'nome_api': data['data']['name']}
 return {'aprovado': False, 'fonte': 'api', 'erro': f'http_{response.status_code}'}
 except Exception as e:
 return {'aprovado': True, 'fonte': 'fallback', 'erro': str(e)}

 def _validar_sintaxe_cpf(self, cpf):
 cpf_limpo = cpf.replace('.', '').replace('-', '')
 return len(cpf_limpo) == 11 and cpf_limpo.isdigit()
```

---

## Estratégia de rollout gradual

Uma abordagem segura para lançar a integração:

| Fase | Percentual | Duração | Critério para avançar |
| --- | --- | --- | --- |
| 1 | 1% | 2 dias | Sem erros críticos |
| 2 | 5% | 3 dias | Latência dentro do esperado |
| 3 | 20% | 5 dias | Consumo de cota dentro do previsto |
| 4 | 50% | 5 dias | Métricas estáveis |
| 5 | 100% | Permanente | Tudo funcionando |

### Script de rollout

```python
import time

def executar_rollout(flags, flag_name, fases):
 for fase in fases:
 percentual = fase['percentual']
 duracao_horas = fase['duracao_horas']

 print(f'Fase: {percentual}% - Duração: {duracao_horas}h')
 flags.definir_percentual(flag_name, percentual)

 # Monitorar durante a duração da fase
 inicio = time.time()
 while time.time() - inicio < duracao_horas * 3600:
 metricas = coletar_metricas(flag_name)

 # Critérios de rollback automático
 if metricas['taxa_erro'] > 5:
 print(f'Taxa de erro alta ({metricas["taxa_erro"]}%). Rollback!')
 flags.desativar(flag_name)
 return False

 if metricas['latencia_p95'] > 5000:
 print(f'Latência alta ({metricas["latencia_p95"]}ms). Rollback!')
 flags.desativar(flag_name)
 return False

 time.sleep(300) # verificar a cada 5 minutos

 print('Rollout completo!')
 flags.ativar(flag_name)
 return True

# Definir fases
fases = [
 {'percentual': 1, 'duracao_horas': 48},
 {'percentual': 5, 'duracao_horas': 72},
 {'percentual': 20, 'duracao_horas': 120},
 {'percentual': 50, 'duracao_horas': 120},
 {'percentual': 100, 'duracao_horas': 24}
]
```

---

## Feature flags em Node.js

```javascript
class FeatureFlags {
 constructor(redisClient) {
 this.redis = redisClient;
 }

 async estaAtivo(flagName, userId = null) {
 const status = await this.redis.get(`flag:${flagName}:status`);
 if (status === 'disabled') return false;
 if (status === 'enabled') return true;

 const percentual = parseInt(
 await this.redis.get(`flag:${flagName}:percentual`) || '0'
 );

 if (userId) {
 // Hash determinístico
 let hash = 0;
 const str = `${flagName}:${userId}`;
 for (let i = 0; i < str.length; i++) {
 hash = ((hash << 5) - hash) + str.charCodeAt(i);
 hash |= 0;
 }
 return Math.abs(hash) % 100 < percentual;
 }

 return Math.random() * 100 < percentual;
 }
}

// Uso no endpoint
app.post('/api/cadastro', async (req, res) => {
 const { cpf, nome, userId } = req.body;

 const usarAPI = await flags.estaAtivo('validacao_cpf_api', userId);

 if (usarAPI) {
 const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
 method: 'GET',
 headers: {
 'x-api-key': process.env.CPFHUB_API_KEY,
 'Accept': 'application/json'
 },
 signal: AbortSignal.timeout(15000)
 });

 const data = await response.json();
 // processar resultado...
 }

 res.json({ status: 'ok', validacao_api: usarAPI });
});
```

---

## Monitoramento por segmento

Compare as métricas entre usuários com e sem a feature flag ativa:

| Métrica | Com flag ativa | Sem flag ativa |
| --- | --- | --- |
| Taxa de conversão no onboarding | Medir | Medir |
| Tempo médio de cadastro | Medir | Medir |
| Taxa de fraude detectada | Medir | Medir |
| Latência do fluxo | Medir | Medir |

Isso permite avaliar o impacto real da integração antes de ativar para todos.

---

## Rollback instantâneo

Se algo der errado em qualquer fase, desative em um comando:

```python
# Desativar imediatamente
flags.desativar('validacao_cpf_api')

# Verificar
print(flags.esta_ativo('validacao_cpf_api', user_id='qualquer'))
# False
```

O rollback não requer deploy, restart ou qualquer intervenção no código. A mudança é imediata.

---

## Boas práticas

* **Hash determinístico** — Use o user_id para garantir que o mesmo usuário sempre veja o mesmo comportamento (não alterne entre fases).

* **Métricas separadas** — Registre métricas com e sem a flag para comparação.

* **Timeouts adequados** — Na fase inicial, use timeouts mais conservadores para não degradar o fluxo principal.

* **Fallback sempre funcional** — O caminho sem API deve continuar operando normalmente.

* **Documentar cada fase** — Registre quando cada percentual foi ativado e os resultados observados.

---

## Perguntas frequentes

### Como as feature flags ajudam a controlar o consumo de cota da API de CPF?
Com rollout gradual, apenas uma fração dos usuários aciona chamadas reais à API inicialmente. Isso permite calibrar o consumo de cota conforme a demanda real, evitando picos inesperados que possam ultrapassar o limite do plano e gerar cobranças excedentes de R$0,15 por consulta.

### O que acontece se a API de CPF ficar lenta durante o rollout?
O script de rollout automático monitora a latência P95. Se ultrapassar o limiar configurado (ex: 5.000ms), o rollback é acionado em segundos via Redis, sem necessidade de deploy. O fluxo de cadastro original continua operando normalmente para todos os usuários.

### Posso usar feature flags para testar a integração com a CPFHub.io em produção?
Sim. A abordagem recomendada é ativar para 1% dos usuários reais em produção, validar que os dados retornados pela API estão corretos e que o consumo de cota está dentro do esperado, e então expandir gradualmente. A API CPFHub.io responde em ~900ms — monitore a latência de ponta a ponta no seu fluxo.

### Como garantir que o mesmo usuário veja sempre o mesmo comportamento durante o rollout?
Use hash determinístico baseado no user_id concatenado com o nome da flag. Isso garante que um usuário no grupo de 5% permaneça nesse grupo em todas as requisições, sem alternar entre o fluxo com e sem validação de CPF.

### Leia também

- [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)
- [Como otimizar o uso das 50 consultas gratuitas mensais da CPFHub.io](https://cpfhub.io/blog/como-otimizar-o-uso-das-50-consultas-gratuitas-mensais-da-cpfhub-io)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [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)

---

## Conclusão

Feature flags transformam o lançamento de uma integração com API de CPF de um evento de alto risco em um processo controlado e reversível. Com rollout gradual, monitoramento por segmento e rollback instantâneo via Redis, você integra novas funcionalidades com confiança, protegendo seus usuários e mantendo o consumo de cota previsível.

A abordagem funciona tanto para equipes que estão começando com o plano gratuito de 50 consultas quanto para operações maiores no plano Pro. O importante é ter visibilidade sobre cada fase antes de avançar. Crie sua conta gratuita em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas por mês, sem cartão de crédito, para começar seus testes com segurança.