Feature flags para rollout gradual de integrações com API de 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.

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

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

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

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

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:

# 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.

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 — 50 consultas por mês, sem cartão de crédito, para começar seus testes com segurança.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

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