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

> Aprenda a integrar validação de CPF em Google Cloud Functions usando Python e requests. Exemplos com HTTP trigger, Secret Manager e deploy.

**Publicado:** 03/10/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-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](https://www.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

```python
# 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:

```python
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:

```bash
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:

```json
{
 "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

```bash
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:

```bash
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

```bash
# 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:

```bash
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](https://www.gov.br/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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [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)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.