Validação de CPF para empresas de saneamento e abastecimento de água

Empresas de saneamento e abastecimento de água podem usar a API CPFHub.io para validar o CPF de titulares em ligações novas, transferências, negociações de débito e concessão de tarifa social — reduzindo fraudes e mantendo cadastros consistentes. O plano gratuito oferece 50 consultas mensais sem cartão de crédito, com integração em menos de 30 minutos.

Introdução

O setor de saneamento básico no Brasil passa por uma transformação significativa após o Marco Legal do Saneamento (Lei 14.026/2020), que estabeleceu metas ambiciosas de universalização dos serviços de água e esgoto. Com a entrada de novos operadores privados e a modernização das companhias estaduais, a gestão comercial dos serviços de saneamento ganha cada vez mais importância.

A correta identificação dos titulares de ligações de água e esgoto é fundamental para a saúde financeira das empresas de saneamento. O CPF é o identificador base dos consumidores pessoa física, e sua validação via API permite reduzir fraudes, manter cadastros consistentes e agilizar processos comerciais.

Processos comerciais que dependem do CPF

Ligação de água nova

Quando um novo consumidor solicita ligação de água, a empresa de saneamento precisa do CPF para criar o cadastro do titular e emitir as faturas.

Transferência de titularidade

A troca de proprietário ou locatário do imóvel exige a transferência da conta de água para o novo responsável, com validação do CPF.

Negociação de débitos

Consumidores inadimplentes que buscam negociar dívidas precisam ter a identidade confirmada para evitar que terceiros negociem débitos de forma fraudulenta.

Tarifa social

Famílias de baixa renda podem ter direito à tarifa social de água. A concessão do benefício exige a identificação do titular por meio do CPF.

Ligação de esgoto

A obrigatoriedade de conexão à rede de esgoto, quando disponível, exige cadastro do titular com CPF validado.

Desafios específicos do setor de saneamento

Base de clientes antiga e desatualizada

Muitas companhias de saneamento possuem bases de clientes com décadas de existência, contendo CPFs inválidos, duplicados ou desatualizados. A revalidação em massa é essencial para a modernização.

Alta inadimplência

O setor de saneamento enfrenta taxas de inadimplência significativas. A correta identificação do devedor é fundamental para ações de cobrança eficazes.

Ligações clandestinas

Ligações clandestinas de água (gatos) são um problema crônico. Quando identificadas e regularizadas, a validação de CPF do novo titular garante que a regularização é legítima.

Universalização dos serviços

Com as metas de universalização, novas ligações estão sendo feitas em áreas antes não atendidas, muitas vezes em comunidades com menor acesso a documentação formal. A validação de CPF ajuda a formalizar esses novos consumidores.

Implementação com Python

import requests
from datetime import datetime

CPFHUB_API_KEY = "sua_api_key_aqui"
CPFHUB_BASE_URL = "https://api.cpfhub.io/cpf"
TIMEOUT_SECONDS = 10

def solicitar_ligacao_agua(cpf: str, nome: str,
    endereco: str, categoria: str) -> dict:
    """
    Processa solicitação de ligação de água após validar o CPF.
    categoria: residencial, comercial, industrial, publica
    """
    cpf_limpo = cpf.replace(".", "").replace("-", "")

    if len(cpf_limpo) != 11 or not cpf_limpo.isdigit():
    return {"aprovado": False, "motivo": "CPF inválido"}

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

    try:
    response = requests.get(
    f"{CPFHUB_BASE_URL}/{cpf_limpo}",
    headers=headers,
    timeout=TIMEOUT_SECONDS
    )
    response.raise_for_status()
    resultado = response.json()
    except requests.exceptions.Timeout:
    return {"aprovado": False, "motivo": "Timeout na validação"}
    except requests.exceptions.RequestException as e:
    return {"aprovado": False, "motivo": f"Erro: {str(e)}"}

    if not resultado.get("success"):
    return {"aprovado": False, "motivo": "CPF não encontrado"}

    dados = resultado["data"]
    nome_api = dados.get("nameUpper", "").strip()
    nome_titular = nome.strip().upper()

    if nome_api != nome_titular:
    return {
    "aprovado": False,
    "motivo": "Nome divergente",
    "nome_base": nome_api,
    "nome_informado": nome_titular
    }

    solicitacao = {
    "matricula": f"AG-{datetime.now().strftime('%Y%m%d%H%M%S')}",
    "titular": {
    "cpf": dados["cpf"],
    "nome": dados["name"],
    "data_nascimento": dados["birthDate"]
    },
    "endereco": endereco,
    "categoria": categoria,
    "data_solicitacao": datetime.now().isoformat(),
    "status": "pendente_vistoria"
    }

    return {"aprovado": True, "solicitacao": solicitacao}

# Exemplo de uso
resultado = solicitar_ligacao_agua(
    cpf="123.456.789-09",
    nome="Luciana Pereira dos Santos",
    endereco="Av. Brasil, 500, Bairro Jardim, Cidade/UF",
    categoria="residencial"
)

if resultado["aprovado"]:
    s = resultado["solicitacao"]
    print(f"Matrícula: {s['matricula']}")
    print(f"Titular: {s['titular']['nome']}")
    print(f"Categoria: {s['categoria']}")
    print(f"Status: {s['status']}")
else:
    print(f"Solicitação negada: {resultado['motivo']}")

Consulta via cURL

curl -X GET "https://api.cpfhub.io/cpf/12345678909" \
    -H "x-api-key: sua_api_key_aqui" \
    -H "Accept: application/json" \
    --max-time 10

Resposta:

{
    "success": true,
    "data": {
    "cpf": "123.456.789-09",
    "name": "Luciana Pereira dos Santos",
    "nameUpper": "LUCIANA PEREIRA DOS SANTOS",
    "gender": "F",
    "birthDate": "12/04/1990",
    "day": "12",
    "month": "04",
    "year": "1990"
    }
}

Revalidação da base de clientes

Companhias de saneamento com bases antigas podem revalidar os CPFs em lote para atualizar cadastros e identificar inconsistências.

const axios = require("axios");

const CPFHUB_API_KEY = "sua_api_key_aqui";
const CPFHUB_BASE_URL = "https://api.cpfhub.io/cpf";

async function revalidarBase(clientes) {
    const resultados = {
    validos: [],
    divergentes: [],
    naoEncontrados: [],
    erros: []
    };

    for (const cliente of clientes) {
    const cpfLimpo = cliente.cpf.replace(/\D/g, "");

    try {
    const response = await axios.get(`${CPFHUB_BASE_URL}/${cpfLimpo}`, {
    headers: {
    "x-api-key": CPFHUB_API_KEY,
    Accept: "application/json"
    },
    timeout: 10000
    });

    const resultado = response.data;

    if (!resultado.success) {
    resultados.naoEncontrados.push({
    matricula: cliente.matricula,
    cpf: cliente.cpf,
    nome: cliente.nome
    });
    continue;
    }

    const nomeApi = resultado.data.nameUpper;
    const nomeCadastro = cliente.nome.toUpperCase().trim();

    if (nomeApi === nomeCadastro) {
    resultados.validos.push({
    matricula: cliente.matricula,
    cpf: resultado.data.cpf,
    nome: resultado.data.name
    });
    } else {
    resultados.divergentes.push({
    matricula: cliente.matricula,
    cpf: cliente.cpf,
    nomeCadastro: cliente.nome,
    nomeBase: resultado.data.name
    });
    }
    } catch (error) {
    resultados.erros.push({
    matricula: cliente.matricula,
    cpf: cliente.cpf,
    erro: error.message
    });
    }

    // Aguardar entre consultas para respeitar rate limiting
    await new Promise((resolve) => setTimeout(resolve, 500));
    }

    return resultados;
}

// Exemplo de uso
(async () => {
    const clientes = [
    { matricula: "AG-001", cpf: "123.456.789-09", nome: "Luciana Pereira dos Santos" },
    { matricula: "AG-002", cpf: "987.654.321-00", nome: "Pedro Henrique Silva" },
    { matricula: "AG-003", cpf: "456.789.123-45", nome: "Nome Incorreto" }
    ];

    const resultado = await revalidarBase(clientes);

    console.log(`Válidos: ${resultado.validos.length}`);
    console.log(`Divergentes: ${resultado.divergentes.length}`);
    console.log(`Não encontrados: ${resultado.naoEncontrados.length}`);
    console.log(`Erros: ${resultado.erros.length}`);
})();

Tarifa social e validação de CPF

A concessão de tarifa social requer a identificação do titular da ligação. A validação de CPF pode ser combinada com a consulta ao CadÚnico para verificar se o consumidor atende aos critérios de elegibilidade. Esse processo automatizado agiliza a concessão do benefício e reduz fraudes.

Boas práticas para empresas de saneamento

• Validação em todos os pontos de contato -- Ligação nova, transferência, negociação e tarifa social devem incluir validação de CPF.
• Campanha de atualização cadastral -- Realize campanhas periódicas para revalidar a base existente, oferecendo benefícios para consumidores que atualizem seus dados.
• Integração com sistemas comerciais -- Conecte a API de validação aos sistemas TOTVS, SAP ou outros utilizados pela companhia.
• Atendimento multicanal -- Integre a validação nos canais presencial, telefônico e digital para uma experiência consistente.
• Proteção de dados -- Trate os dados dos consumidores conforme a LGPD, garantindo transparência e segurança. A ANPD orienta que o tratamento de dados de identificação deve observar os princípios da finalidade e da necessidade.

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 com latência de ~900ms, 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

A validação de CPF é uma ferramenta essencial para empresas de saneamento que buscam modernizar sua gestão comercial, reduzir fraudes e atender às metas de universalização estabelecidas pelo Marco Legal do Saneamento.

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