# Como integrar validação de CPF em aplicações HTMX sem JavaScript pesado
> Aprenda a integrar validação de CPF em aplicações HTMX usando atributos HTML e um backend leve para consumir a API da CPFHub.io.
**Publicado:** 24/07/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-aplicacoes-htmx-sem-javascript-pesado
---
O **HTMX** permite criar interfaces dinâmicas usando atributos HTML que fazem requisições AJAX e atualizam parcialmente a página — sem bundlers, sem build steps, sem megabytes de JavaScript. Para validar CPF em tempo real, o HTMX envia o número para o backend, que consulta a API da CPFHub.io e retorna um fragmento HTML com o resultado, mantendo toda a chave de API protegida no servidor. A latência da API é de aproximadamente 900ms, o que torna o uso de indicadores de loading no HTMX indispensável para uma boa experiência. Confira a [documentação oficial do HTMX](https://htmx.org/docs/) para entender o modelo de atributos antes de começar.
---
## 1. Pré-requisitos
* **Python 3.9+** instalado.
* Pacotes: `pip install flask requests`.
* Uma conta gratuita na [**CPFHub.io**](https://www.cpfhub.io/)
---
## 2. Estrutura do projeto
```
htmx-cpf-app/
├── app.py
├── .env
├── templates/
│ ├── base.html
│ ├── index.html
│ └── partials/
│ ├── resultado.html
│ ├── erro.html
│ └── loading.html
└── static/
└── style.css
```
---
## 3. Configure o backend Flask
Crie o servidor Flask com as rotas para HTMX:
```python
# app.py
import os
import re
import requests
from flask import Flask, render_template, request
app = Flask(__name__)
CPFHUB_API_KEY = os.getenv("CPFHUB_API_KEY", "SUA_CHAVE_DE_API")
CPFHUB_BASE_URL = os.getenv("CPFHUB_BASE_URL", "https://api.cpfhub.io")
CPFHUB_TIMEOUT = int(os.getenv("CPFHUB_TIMEOUT", "5"))
def consultar_cpf(cpf: str) -> dict:
"""Consulta CPF na API da CPFHub.io."""
cpf_limpo = re.sub(r"\D", "", cpf)
if len(cpf_limpo) != 11:
return {"error": "CPF deve conter exatamente 11 dígitos."}
url = f"{CPFHUB_BASE_URL}/cpf/{cpf_limpo}"
headers = {
"x-api-key": CPFHUB_API_KEY,
"Accept": "application/json",
}
try:
response = requests.get(url, headers=headers, timeout=CPFHUB_TIMEOUT)
except requests.exceptions.Timeout:
return {"error": "Timeout ao consultar a API. Tente novamente."}
except requests.exceptions.RequestException as e:
return {"error": f"Erro de conexão: {str(e)}"}
if response.status_code == 200:
data = response.json()
if data.get("success"):
return {"data": data["data"]}
return {"error": "Resposta inesperada da API."}
error_map = {
400: "CPF com formato inválido.",
401: "Chave de API inválida.",
404: "CPF não encontrado na base de dados.",
}
return {"error": error_map.get(response.status_code, f"Erro HTTP {response.status_code}")}
@app.route("/")
def index():
"""Página principal."""
return render_template("index.html")
@app.route("/consultar-cpf", methods=["POST"])
def consultar_cpf_endpoint():
"""Endpoint HTMX para consulta de CPF. Retorna fragmento HTML."""
cpf = request.form.get("cpf", "").strip()
if not cpf:
return render_template("partials/erro.html", mensagem="Digite um CPF.")
resultado = consultar_cpf(cpf)
if "error" in resultado:
return render_template("partials/erro.html", mensagem=resultado["error"])
return render_template("partials/resultado.html", dados=resultado["data"])
if __name__ == "__main__":
app.run(debug=True, port=5000)
```
---
## 4. Crie o template base
```html
Consulta de CPF - HTMX
{% block content %}{% endblock %}
```
---
## 5. Crie a página de consulta com HTMX
A mágica do HTMX está nos atributos HTML:
```html
{% extends "base.html" %}
{% block content %}
Consulta de CPF
Validacao de CPF em tempo real via CPFHub.io
Consultando...
{% endblock %}
```
---
## 6. Crie os fragmentos HTML (partials)
O HTMX trabalha com fragmentos HTML retornados pelo servidor:
```html
```
```python
# app.py (rota adicional para lote)
import csv
import io
@app.route("/consultar-lote", methods=["POST"])
def consultar_lote():
"""Endpoint HTMX para consulta em lote via CSV."""
arquivo = request.files.get("arquivo")
if not arquivo:
return render_template("partials/erro.html", mensagem="Envie um arquivo CSV.")
conteudo = arquivo.read().decode("utf-8")
reader = csv.DictReader(io.StringIO(conteudo))
resultados = []
for row in reader:
cpf = row.get("cpf", "")
resultado = consultar_cpf(cpf)
resultados.append({
"cpf": cpf,
"resultado": resultado,
})
return render_template("partials/resultado_lote.html", resultados=resultados)
```
---
## 10. Boas práticas
* **Progressividade** -- O HTMX funciona como progressive enhancement. O formulário funciona mesmo sem JavaScript (via POST normal).
* **Debounce** -- Use `hx-trigger="keyup changed delay:500ms"` para evitar consultas a cada tecla digitada.
* **Indicadores** -- Use `hx-indicator` para feedback visual durante a requisição, melhorando a UX.
* **Segurança** -- A chave de API fica exclusivamente no backend. O HTMX apenas envia o CPF digitado pelo usuário.
* **Timeout** -- Configure timeout de 5 segundos nas requisições do backend, alinhado com o tempo de ~900ms da API.
* **LGPD** -- A API da CPFHub.io é 100% compatível com a LGPD. Adicione informações de consentimento no formulário conforme a legislação.
---
## Perguntas frequentes
### O que é necessário para implementar validação de CPF com HTMX?
A validação de CPF com HTMX exige um backend que receba o CPF via POST, consulte a API da CPFHub.io com a chave `x-api-key` e retorne um fragmento HTML. O HTMX cuida de substituir o conteúdo da página sem recarregamento, tornando a experiência fluida sem nenhum JavaScript escrito manualmente no frontend.
### A chave de API fica exposta no HTML com HTMX?
Não. O HTMX faz a requisição para o seu próprio backend (por exemplo, `/consultar-cpf`), e é o servidor que adiciona a chave de API ao chamar a CPFHub.io. O navegador nunca vê a chave, o que é a abordagem correta para qualquer aplicação em produção.
### A API da CPFHub.io bloqueia requisições quando o limite do plano é atingido?
Não. Ao atingir o limite do plano gratuito (50 consultas/mês), a API continua respondendo normalmente e cobra R$0,15 por consulta adicional. Não há bloqueio nem código de erro 429 por cota esgotada — o que torna o comportamento previsível para aplicações em produção.
### Quanto tempo a API leva para responder em aplicações HTMX?
A latência da API da CPFHub.io é de aproximadamente 900ms. Por isso, o uso de `hx-indicator` é importante: exibe uma mensagem de carregamento enquanto a requisição do backend à API é processada, evitando que o usuário ache que o formulário travou.
---
### 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)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)
- [Como consumir API de CPF em Alpine.js com fetch e x-data](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-alpine-js-com-fetch-e-x-data)
---
## Conclusão
Integrar a API da [**CPFHub.io**](https://www.cpfhub.io/)
Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)