Como integrar validação de CPF em Google Cloud Functions com Python

Integrar validação de CPF em Google Cloud Functions com Python é direto: basta criar uma função HTTP trigger que chama GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e retorna os dados estruturados do titular. A CPFHub.io entrega resposta em aproximadamente 900ms, com conformidade LGPD e 99,9% de uptime — e você pode começar com 50 consultas gratuitas por mês, sem cartão de crédito.

Introdução

O Google Cloud Functions é a plataforma serverless do Google Cloud, ideal para executar funções isoladas em resposta a eventos HTTP, mensagens do Pub/Sub ou alterações no Cloud Storage. Combinado com Python -- uma das linguagens mais populares para desenvolvimento de APIs e automação --, o Cloud Functions oferece uma forma rápida e escalável de implementar validação de CPF.

1. Pré-requisitos

• Conta no Google Cloud -- Com um projeto ativo e billing habilitado.

• gcloud CLI instalado -- Para deploy e gerenciamento das funções.

• Python 3.11 ou superior -- Runtime suportado pelo Cloud Functions (2nd gen).

• Conta na CPFHub.io -- Cadastre-se em cpfhub.io e gere sua API key no painel para usar nos exemplos abaixo.

2. Estrutura do projeto

cpf-validation/
├── main.py
├── requirements.txt
└── .gcloudignore

requirements.txt

functions-framework==3.*
requests>=2.31.0
google-cloud-secret-manager>=2.16.0

3. Implementação da função

Versão básica com variável de ambiente

# main.py
import os
import re
import requests
import functions_framework

CPFHUB_API_KEY = os.environ.get('CPFHUB_API_KEY')
CPFHUB_BASE_URL = 'https://api.cpfhub.io/cpf'
TIMEOUT = 30

def consultar_cpf(cpf: str) -> dict | None:
    """Consulta um CPF na API da CPFHub.io."""
    cpf_limpo = re.sub(r'\D', '', cpf)

    headers = {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json',
    }

    try:
    response = requests.get(
    f'{CPFHUB_BASE_URL}/{cpf_limpo}',
    headers=headers,
    timeout=TIMEOUT,
    )

    if response.status_code == 200:
    data = response.json()
    if data.get('success'):
    return data['data']

    return None

    except requests.exceptions.Timeout:
    print(f'Timeout ao consultar CPF {cpf_limpo}')
    return None
    except requests.exceptions.RequestException as e:
    print(f'Erro ao consultar CPF {cpf_limpo}: {e}')
    return None

@functions_framework.http
def validar_cpf(request):
    """HTTP Cloud Function para validação de CPF."""
    # Permitir CORS
    if request.method == 'OPTIONS':
    headers = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET',
    'Access-Control-Allow-Headers': 'Content-Type',
    }
    return ('', 204, headers)

    cors_headers = {'Access-Control-Allow-Origin': '*'}

    # Extrair CPF da URL ou query string
    cpf = request.args.get('cpf', '')

    if not cpf:
    # Tentar extrair do path
    path = request.path.strip('/')
    parts = path.split('/')
    if parts:
    cpf = parts[-1]

    cpf_limpo = re.sub(r'\D', '', cpf)

    if len(cpf_limpo) != 11:
    return (
    {'error': 'CPF deve conter 11 digitos numericos.'},
    400,
    cors_headers,
    )

    dados = consultar_cpf(cpf_limpo)

    if dados:
    return (
    {
    'success': True,
    'data': {
    'cpf': dados['cpf'],
    'name': dados['name'],
    'nameUpper': dados['nameUpper'],
    'gender': dados['gender'],
    'birthDate': dados['birthDate'],
    'day': dados['day'],
    'month': dados['month'],
    'year': dados['year'],
    },
    },
    200,
    cors_headers,
    )

    return (
    {'error': 'CPF nao encontrado ou invalido.'},
    404,
    cors_headers,
    )

4. Usando Google Secret Manager

Para armazenamento seguro da chave de API em produção:

from google.cloud import secretmanager

_cached_api_key = None

def get_api_key() -> str:
    """Recupera a chave de API do Secret Manager com cache."""
    global _cached_api_key

    if _cached_api_key:
    return _cached_api_key

    # Tentar variável de ambiente primeiro (desenvolvimento local)
    env_key = os.environ.get('CPFHUB_API_KEY')
    if env_key:
    _cached_api_key = env_key
    return _cached_api_key

    # Recuperar do Secret Manager
    client = secretmanager.SecretManagerServiceClient()
    project_id = os.environ.get('GCP_PROJECT')
    name = f'projects/{project_id}/secrets/cpfhub-api-key/versions/latest'

    response = client.access_secret_version(request={'name': name})
    _cached_api_key = response.payload.data.decode('UTF-8')

    return _cached_api_key

Crie o segredo no Secret Manager:

echo -n "SUA_CHAVE_DE_API" | gcloud secrets create cpfhub-api-key --data-file=-

5. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com todos os dados cadastrais do titular. Veja o formato completo:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success -- Indica se a consulta foi bem-sucedida.
• name / nameUpper -- Nome completo do titular.
• gender -- Gênero (M ou F).
• birthDate -- Data de nascimento completa.
• day, month, year -- Componentes da data separados.

6. Deploy

Deploy via gcloud CLI

gcloud functions deploy validar-cpf \
    --gen2 \
    --runtime python311 \
    --trigger-http \
    --allow-unauthenticated \
    --region southamerica-east1 \
    --set-env-vars CPFHUB_API_KEY=SUA_CHAVE_DE_API \
    --timeout 30s \
    --memory 256MB \
    --entry-point validar_cpf

Para usar o Secret Manager em vez de variável de ambiente:

gcloud functions deploy validar-cpf \
    --gen2 \
    --runtime python311 \
    --trigger-http \
    --allow-unauthenticated \
    --region southamerica-east1 \
    --set-env-vars GCP_PROJECT=meu-projeto \
    --set-secrets 'CPFHUB_API_KEY=cpfhub-api-key:latest' \
    --timeout 30s \
    --memory 256MB \
    --entry-point validar_cpf

7. Testando localmente

# Instalar o framework de funções
pip install functions-framework

# Executar localmente
CPFHUB_API_KEY=SUA_CHAVE_DE_API functions-framework --target validar_cpf --port 8080

Em outro terminal:

curl -X GET "http://localhost:8080/?cpf=12345678900" \
    --max-time 30

8. Boas práticas

• Escolha a região adequada -- Para menor latência no Brasil, utilize southamerica-east1 (São Paulo).

• Configure timeout -- Defina o timeout da função para pelo menos 30 segundos, considerando o tempo de resposta da API (~900ms).

• Use Secret Manager -- Armazene a chave de API no Secret Manager em vez de variáveis de ambiente para maior segurança.

• Implemente cache -- Utilize Memorystore (Redis) ou Firestore para armazenar resultados de consultas recentes.

• Monitore com Cloud Logging -- Configure alertas para erros e latência elevada.

• Respeite rate limits -- O plano gratuito oferece 50 consultas mensais sem cartão de crédito. O plano Pro (R$ 149/mês) oferece 1.000 consultas com SLA de 99%.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

O Google Cloud Functions com Python oferece uma plataforma serverless eficiente para validação de CPF. A integração com a API da CPFHub.io é direta — poucos minutos de configuração e sua função está pronta para processar validações em escala, com latência de aproximadamente 900ms, 99,9% de uptime e conformidade com a LGPD.

Com suporte a Python como uma das 13+ linguagens documentadas, a integração com Cloud Functions é simples e segura, seja usando variáveis de ambiente para desenvolvimento ou o Secret Manager para produção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.