Validação de CPF em 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 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

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:

# 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

<!-- templates/base.html -->
<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Consulta de CPF - HTMX</title>
    <script src="https://unpkg.com/htmx.org@2.0.0"></script>
    <link rel="stylesheet" href="/static/style.css">
</head>
<body>
    <div class="container">
    {% block content %}{% endblock %}
    </div>
</body>
</html>

5. Crie a página de consulta com HTMX

A mágica do HTMX está nos atributos HTML:

<!-- templates/index.html -->
{% extends "base.html" %}

{% block content %}
<h1>Consulta de CPF</h1>
<p>Validacao de CPF em tempo real via <strong>CPFHub.io</strong></p>

<form
    hx-post="/consultar-cpf"
    hx-target="#resultado"
    hx-swap="innerHTML"
    hx-indicator="#loading"
>
    <div class="form-group">
    <label for="cpf">CPF</label>
    <input
    type="text"
    id="cpf"
    name="cpf"
    placeholder="000.000.000-00"
    maxlength="14"
    required
    hx-post="/consultar-cpf"
    hx-trigger="keyup changed delay:500ms"
    hx-target="#resultado"
    hx-indicator="#loading"
    />
    </div>

    <button type="submit">Consultar</button>
</form>

<div id="loading" class="htmx-indicator">
    Consultando...
</div>

<div id="resultado"></div>
{% endblock %}

6. Crie os fragmentos HTML (partials)

O HTMX trabalha com fragmentos HTML retornados pelo servidor:

<!-- templates/partials/resultado.html -->
<div class="card sucesso">
    <h3>CPF Encontrado</h3>
    <table>
    <tr>
    <td><strong>Nome</strong></td>
    <td>{{ dados.name }}</td>
    </tr>
    <tr>
    <td><strong>CPF</strong></td>
    <td>{{ dados.cpf }}</td>
    </tr>
    <tr>
    <td><strong>Genero</strong></td>
    <td>{{ dados.gender }}</td>
    </tr>
    <tr>
    <td><strong>Nascimento</strong></td>
    <td>{{ dados.birthDate }}</td>
    </tr>
    </table>
</div>

<!-- templates/partials/erro.html -->
<div class="card erro">
    <p>{{ mensagem }}</p>
</div>

7. Adicione estilos CSS

/* static/style.css */
* { box-sizing: border-box; margin: 0; padding: 0; }

body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    background: #f5f5f5;
    color: #333;
    line-height: 1.6;
}

.container {
    max-width: 600px;
    margin: 40px auto;
    padding: 0 20px;
}

h1 { margin-bottom: 8px; }
p { margin-bottom: 24px; color: #666; }

.form-group {
    margin-bottom: 16px;
}

label {
    display: block;
    margin-bottom: 4px;
    font-weight: 600;
}

input[type="text"] {
    width: 100%;
    padding: 12px;
    font-size: 16px;
    border: 2px solid #ddd;
    border-radius: 6px;
    transition: border-color 0.2s;
}

input[type="text"]:focus {
    outline: none;
    border-color: #3498db;
}

button {
    padding: 12px 24px;
    font-size: 16px;
    background: #3498db;
    color: white;
    border: none;
    border-radius: 6px;
    cursor: pointer;
    transition: background 0.2s;
}

button:hover { background: #2980b9; }

.card {
    margin-top: 24px;
    padding: 20px;
    border-radius: 8px;
    border: 1px solid #ddd;
}

.card.sucesso {
    border-color: #27ae60;
    background: #f0fff4;
}

.card.erro {
    border-color: #e74c3c;
    background: #fff5f5;
    color: #c0392b;
}

table { width: 100%; border-collapse: collapse; margin-top: 12px; }
td { padding: 8px 0; border-bottom: 1px solid #eee; }
td:first-child { width: 120px; }

.htmx-indicator {
    display: none;
    margin-top: 16px;
    color: #888;
    font-style: italic;
}

.htmx-request .htmx-indicator {
    display: block;
}

.htmx-request button {
    opacity: 0.6;
    cursor: wait;
}

8. Recursos avançados do HTMX

Adicione validação em tempo real com debounce e indicadores de loading:

<!-- Validação on-blur (quando o campo perde foco) -->
<input
    type="text"
    name="cpf"
    hx-post="/consultar-cpf"
    hx-trigger="blur"
    hx-target="#resultado"
    hx-swap="innerHTML transition:true"
    hx-indicator="#loading"
/>

<!-- Consulta com confirmação -->
<button
    hx-post="/consultar-cpf"
    hx-target="#resultado"
    hx-confirm="Deseja consultar este CPF?"
    hx-include="[name='cpf']"
>
    Consultar com Confirmacao
</button>

<!-- Histórico de consultas com hx-push-url -->
<form
    hx-post="/consultar-cpf"
    hx-target="#resultado"
    hx-push-url="/consulta/{cpf}"
>
    <!-- campos do formulário -->
</form>

9. Adicione consulta em lote via HTMX

<!-- templates/index.html (seção de lote) -->
<h2>Consulta em Lote</h2>

<form
    hx-post="/consultar-lote"
    hx-target="#resultado-lote"
    hx-swap="innerHTML"
    hx-indicator="#loading-lote"
    hx-encoding="multipart/form-data"
>
    <input type="file" name="arquivo" accept=".csv" />
    <button type="submit">Enviar CSV</button>
</form>

<div id="loading-lote" class="htmx-indicator">Processando lote...</div>
<div id="resultado-lote"></div>

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

Conclusão

Integrar a API da CPFHub.io

Cadastre-se em cpfhub.io

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 integrar validação de CPF em aplicações HTMX sem JavaScript pesado