Consulta de CPF grátis para ONGs: como validar dados de doadores

ONGs podem validar o CPF de doadores gratuitamente usando a API da CPFHub.io: basta cadastrar-se, gerar uma chave e fazer uma chamada GET com o número do documento. O plano Gratuito oferece 50 consultas por mês sem cartão de crédito — suficiente para a maioria das organizações de pequeno e médio porte. A validação confirma o nome do titular em ~150 ms, garantindo recibos com dados corretos e proteção contra doações fraudulentas.

Por que ONGs precisam validar CPF de doadores

Emissão de recibos para dedução no IR

Doações para ONGs com certificação de utilidade pública podem ser deduzidas no Imposto de Renda. Para isso, o recibo precisa conter o nome e CPF corretos do doador. Um recibo com dados errados não tem validade fiscal.

Prevenção à lavagem de dinheiro

ONGs podem ser usadas como fachada para lavagem de dinheiro. Doações de valores significativos feitas com CPFs falsos ou de terceiros são um sinal de alerta. A validação do CPF é uma medida básica de prevenção.

Prestação de contas

Organizações que recebem recursos públicos ou de fundações precisam prestar contas detalhadas sobre seus doadores. Dados incorretos comprometem a credibilidade da prestação de contas.

Transparência institucional

Manter um cadastro de doadores com dados validados demonstra seriedade e profissionalismo na gestão da organização.

Como funciona na prática

Consulta rápida via cURL

curl -X GET "https://api.cpfhub.io/cpf/12345678900" \
    -H "x-api-key: SUA_CHAVE_GRATUITA" \
    -H "Accept: application/json" \
    --connect-timeout 10 \
    --max-time 30

Resposta:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Juliana Mendes Barbosa",
    "nameUpper": "JULIANA MENDES BARBOSA",
    "gender": "F",
    "birthDate": "1978-12-03",
    "day": "03",
    "month": "12",
    "year": "1978"
    }
}

O nome "JULIANA MENDES BARBOSA" vai para o recibo de doação com a certeza de que está correto.

Implementação para o sistema de doações

Validação no momento da doação

import requests
import logging
from typing import Dict, Optional

logger = logging.getLogger(__name__)

API_KEY = "SUA_CHAVE_GRATUITA"
TIMEOUT = 30

def validar_doador(cpf: str, nome_informado: str) -> Dict:
    """
    Valida CPF do doador e compara com o nome informado.

    Returns:
    Dicionário com status da validação e dados para o recibo
    """
    cpf_limpo = cpf.replace(".", "").replace("-", "").strip()

    try:
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf_limpo}",
    headers={
    "x-api-key": API_KEY,
    "Accept": "application/json"
    },
    timeout=TIMEOUT
    )
    response.raise_for_status()
    dados = response.json()

    if not dados.get("success"):
    return {
    "valido": False,
    "motivo": "CPF nao encontrado",
    "dados_recibo": None
    }

    nome_api = dados["data"]["nameUpper"]
    nome_confere = nome_informado.upper().strip() == nome_api

    cpf_fmt = f"{cpf_limpo[:3]}.{cpf_limpo[3:6]}.{cpf_limpo[6:9]}-{cpf_limpo[9:]}"

    if nome_confere:
    return {
    "valido": True,
    "motivo": "Dados confirmados",
    "dados_recibo": {
    "nome_completo": dados["data"]["name"],
    "cpf_formatado": cpf_fmt,
    "nascimento": dados["data"]["birthDate"]
    }
    }
    else:
    return {
    "valido": False,
    "motivo": f"Nome divergente: informado='{nome_informado}' / registrado='{dados['data']['name']}'",
    "dados_recibo": None,
    "nome_sugerido": dados["data"]["name"]
    }

    except requests.exceptions.Timeout:
    logger.error("Timeout ao validar doador")
    return {"valido": None, "motivo": "Servico indisponivel", "dados_recibo": None}
    except requests.exceptions.RequestException as e:
    logger.error(f"Erro: {e}")
    return {"valido": None, "motivo": f"Erro: {e}", "dados_recibo": None}

# Exemplo de uso
resultado = validar_doador(
    cpf="123.456.789-00",
    nome_informado="Juliana Mendes Barbosa"
)

if resultado["valido"]:
    recibo = resultado["dados_recibo"]
    print(f"Recibo para: {recibo['nome_completo']}")
    print(f"CPF: {recibo['cpf_formatado']}")
else:
    print(f"Validacao falhou: {resultado['motivo']}")

Gerando recibos de doação com dados validados

from datetime import datetime

def gerar_recibo_doacao(dados_doador: Dict, valor: float, descricao: str) -> str:
    """Gera recibo de doação com dados validados via API."""
    data_atual = datetime.now().strftime("%d/%m/%Y")
    numero_recibo = datetime.now().strftime("%Y%m%d%H%M%S")

    recibo = f"""
    =============================================
    RECIBO DE DOACAO N. {numero_recibo}
    =============================================

    Data: {data_atual}

    Doador: {dados_doador['nome_completo']}
    CPF: {dados_doador['cpf_formatado']}

    Valor: R$ {valor:,.2f}
    Descricao: {descricao}

    =============================================
    Este recibo e valido para fins de deducao
    no Imposto de Renda conforme legislacao vigente.
    =============================================
    """

    return recibo

# Uso
resultado = validar_doador("123.456.789-00", "Juliana Mendes Barbosa")
if resultado["valido"]:
    recibo = gerar_recibo_doacao(
    dados_doador=resultado["dados_recibo"],
    valor=500.00,
    descricao="Doacao para projeto educacional"
    )
    print(recibo)

Validação em lote de base de doadores

ONGs com bases de doadores existentes podem validar os dados periodicamente:

import csv
import time

def validar_base_doadores(arquivo_csv: str) -> Dict:
    """Valida base de doadores existente e identifica inconsistências."""
    estatisticas = {"total": 0, "validos": 0, "invalidos": 0, "erros": 0}
    inconsistencias = []

    with open(arquivo_csv, "r", encoding="utf-8") as f:
    leitor = csv.DictReader(f)

    for linha in leitor:
    estatisticas["total"] += 1
    cpf = linha.get("cpf", "")
    nome = linha.get("nome", "")

    resultado = validar_doador(cpf, nome)

    if resultado["valido"] is True:
    estatisticas["validos"] += 1
    elif resultado["valido"] is False:
    estatisticas["invalidos"] += 1
    inconsistencias.append({
    "cpf": cpf[:3] + "***" + cpf[-2:],
    "motivo": resultado["motivo"]
    })
    else:
    estatisticas["erros"] += 1

    time.sleep(0.5) # respeitar rate limits

    return {"estatisticas": estatisticas, "inconsistencias": inconsistencias}

Fluxo para campanhas de arrecadação

Durante campanhas de arrecadação com grande volume de doações, a validação pode ser incorporada ao formulário online:

1. Doador preenche nome, CPF e valor da doação no site.
2. Sistema válida o CPF em tempo real via API.
3. Se válido: doação é processada e recibo é gerado automaticamente.
4. Se inválido: doador é informado da inconsistência e pode corrigir os dados.

Essa abordagem evita que doações com dados incorretos entrem no sistema, reduzindo retrabalho posterior.

Custo zero para a maioria das ONGs

A maioria das ONGs opera com volumes que se encaixam perfeitamente no plano Gratuito da CPFHub.io, que oferece 50 créditos mensais sem cartão de crédito. Essa cota grátis não continua depois do fim: a API responde HTTP 403 ("Limite de créditos excedido") e as consultas param. O excedente dos planos pagos, quando existe, está na página de preços. O limite por minuto segue separado, com HTTP 429 e Retry-After.

Boas práticas de proteção de dados

ONGs que lidam com dados de doadores devem observar a LGPD:

• Finalidade: use os dados apenas para a finalidade declarada (emissão de recibos, prestação de contas).
• Minimização: armazene apenas os dados necessários.
• Transparência: informe aos doadores que seus dados serão validados.
• Segurança: proteja o banco de dados de doadores com medidas técnicas adequadas.

A CPFHub.io não armazena os CPFs consultados após retornar a resposta, o que facilita a conformidade com os princípios de minimização e segurança previstos na Lei Geral de Proteção de Dados.

Perguntas frequentes

ONGs precisam de CNPJ para usar a API CPFHub.io gratuitamente?

Não. O plano Gratuito da CPFHub.io está disponível para qualquer pessoa ou organização — basta criar uma conta com e-mail e gerar a chave de API no painel. ONGs, associações e projetos sociais podem começar a validar CPFs de doadores sem burocracia e sem apresentar documentação institucional.

A API retorna erro ou bloqueia quando o limite gratuito é atingido?

Sim, no Grátis. A cota de 50 créditos mensais, quando acaba, pausa as consultas com HTTP 403 e a mensagem "Limite de créditos excedido". Um plano pago pode continuar se tiver excedente — o valor está na página de preços — e o teto de chamadas por minuto responde HTTP 429 com Retry-After. Em campanha, o volume de doadores pode esgotar os 50 créditos e pausar as consultas no Grátis.

Quanto tempo leva para a API retornar o nome do doador?

A latência média é de ~150 ms. Para a maioria dos fluxos de cadastro de doadores, esse tempo é imperceptível para o usuário. Se a validação ocorre em segundo plano (assíncrona), o tempo de resposta não impacta a experiência do doador no formulário.

Como garantir conformidade com a LGPD ao validar CPF de doadores?

Use o CPF apenas para a finalidade declarada (emissão de recibos, prestação de contas), armazene somente o necessário, implemente controle de acesso aos registros de consulta e informe ao doador que seus dados serão verificados. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade e com base legal clara — no caso de ONGs, a base costuma ser obrigação legal ou legítimo interesse devidamente documentado.

Conclusão

A validação de CPF de doadores é uma prática que fortalece a transparência, garante a validade fiscal dos recibos e protege a ONG contra fraudes. Para organizações com orçamento limitado, o plano Gratuito da CPFHub.io cobre o volume de consultas da maioria das ONGs de pequeno e médio porte sem nenhum custo mensal. Quando a organização crescer, o plano Pro (R$149/mês) acompanha o aumento de volume sem mudança de integração.

Cadastre-se em cpfhub.io e comece a validar os dados dos seus doadores ainda hoje.