Como validar CPF na inscrição de vendedores em marketplaces B2C

Validar o CPF na inscrição de vendedores em marketplaces B2C garante que cada vendedor é uma pessoa real e identificável, bloqueando fraudadores antes que causem danos aos compradores. O fluxo envolve consulta à API CPFHub.io, comparação do nome retornado com o nome informado e com o titular da conta bancária de recebimento, e só então a criação da conta em status pendente de aprovação.

Introdução

Marketplaces B2C — plataformas onde vendedores individuais ou pequenas empresas vendem diretamente para consumidores finais — são o formato dominante do e-commerce brasileiro. Mercado Livre, Shopee, Amazon Brasil e dezenas de outros marketplaces verticais dependem de vendedores terceiros para compor seus catálogos. A qualidade e a confiabilidade desses vendedores definem a reputação da plataforma.

A validação de CPF na inscrição de vendedores é o primeiro filtro de segurança. Ela garante que cada vendedor é uma pessoa real, identificável e responsabilizável. O Marco Civil da Internet e as normas do Procon estabelecem a responsabilidade das plataformas sobre danos causados por vendedores que operam em seu ambiente.

Riscos de vendedores não verificados

Golpe do vendedor fantasma

O fraudador cria uma conta de vendedor com dados falsos, publica produtos a preços atrativos, recebe pagamentos e nunca entrega. Quando os compradores reclamam, o vendedor desaparece e cria outra conta.

Produtos falsificados

Vendedores sem verificação de identidade podem comercializar produtos falsificados sem receio de rastreamento. A validação de CPF cria uma cadeia de responsabilidade que desincentiva essa prática.

Lavagem de dinheiro

Contas de vendedores em marketplaces podem ser usadas para lavagem de dinheiro, com transações fictícias entre contas controladas pelo mesmo indivíduo. A unicidade do CPF dificulta a criação de múltiplas contas para esse fim.

Evasão após bloqueio

Vendedores bloqueados por mau comportamento criam novas contas para continuar operando. Sem verificação de CPF, a plataforma não consegue detectar que o "novo" vendedor é o mesmo que foi banido.

Fluxo de inscrição com validação

A inscrição de vendedores deve seguir um processo estruturado que coloca a validação de CPF como requisito central.

Primeiro, o candidato a vendedor preenche o formulário com dados pessoais, incluindo CPF. O sistema valida o CPF via API, confirmando que é real e obtendo o nome, data de nascimento e gênero. O nome retornado é comparado com o nome informado e com o titular da conta bancária de recebimento. Se tudo for consistente, a conta de vendedor é criada em status "Pendente" até a aprovação final.

Implementação em Python

O exemplo a seguir demonstra o fluxo completo de inscrição de vendedores com validação de CPF.

import requests
import re
from datetime import datetime
from typing import Optional
import json
import hashlib

CPFHUB_API_URL = "https://api.cpfhub.io/cpf"
CPFHUB_API_KEY = "SUA_CHAVE_DE_API"
REQUEST_TIMEOUT = 10 # segundos

# Simulação de banco de dados
vendedores = {} # cpf -> vendedor
cpfs_banidos = set() # CPFs bloqueados permanentemente

def consultar_cpf(cpf: str) -> Optional[dict]:
    """Consulta CPF na API CPFHub.io."""
    cpf_limpo = re.sub(r"\D", "", cpf)

    try:
    response = requests.get(
    f"{CPFHUB_API_URL}/{cpf_limpo}",
    headers={
    "x-api-key": CPFHUB_API_KEY,
    "Accept": "application/json",
    },
    timeout=REQUEST_TIMEOUT,
    )
    response.raise_for_status()
    dados = response.json()

    if dados.get("success"):
    return dados["data"]
    return None

    except requests.exceptions.Timeout:
    raise Exception("Timeout na consulta de CPF")
    except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    if status == 404:
    return None
    if status == 401:
    raise Exception("API key inválida")
    raise Exception(f"Erro HTTP {status}")
    except requests.exceptions.RequestException:
    raise Exception("Erro de conexão")

def normalizar_nome(nome: str) -> str:
    """Normaliza nome para comparação."""
    import unicodedata
    normalizado = unicodedata.normalize("NFKD", nome)
    sem_acento = normalizado.encode("ASCII", "ignore").decode("ASCII")
    return sem_acento.upper().strip()

def comparar_nomes(nome1: str, nome2: str) -> dict:
    """Compara dois nomes e retorna análise detalhada."""
    partes1 = normalizar_nome(nome1).split()
    partes2 = normalizar_nome(nome2).split()

    if not partes1 or not partes2:
    return {"corresponde": False, "score": 0, "detalhes": "Nome vazio"}

    primeiro_ok = partes1[0] == partes2[0]
    ultimo_ok = partes1[-1] == partes2[-1]

    partes_comuns = set(partes1) & set(partes2)
    total = max(len(partes1), len(partes2))
    score = len(partes_comuns) / total if total > 0 else 0

    return {
    "corresponde": primeiro_ok and ultimo_ok and score >= 0.6,
    "score": round(score, 2),
    "primeiro_nome": primeiro_ok,
    "ultimo_nome": ultimo_ok,
    }

def inscrever_vendedor(
    cpf: str,
    nome: str,
    email: str,
    telefone: str,
    nome_titular_banco: str,
    banco: str,
    agencia: str,
    conta: str,
    categoria_produtos: str,
) -> dict:
    """Inscreve um novo vendedor com validação completa de CPF."""

    cpf_limpo = re.sub(r"\D", "", cpf)

    # Verificação 1: CPF banido
    if cpf_limpo in cpfs_banidos:
    return {
    "sucesso": False,
    "erro": "Este CPF está impedido de se cadastrar como vendedor",
    "codigo": "CPF_BANIDO",
    }

    # Verificação 2: CPF já cadastrado
    if cpf_limpo in vendedores:
    vendedor_existente = vendedores[cpf_limpo]
    if vendedor_existente["status"] == "ATIVO":
    return {
    "sucesso": False,
    "erro": "Este CPF já possui uma conta de vendedor ativa",
    "codigo": "CPF_DUPLICADO",
    }
    if vendedor_existente["status"] == "BLOQUEADO":
    return {
    "sucesso": False,
    "erro": "Este CPF possui uma conta bloqueada. Entre em contato com o suporte.",
    "codigo": "CPF_BLOQUEADO",
    }

    # Verificação 3: Consulta na API CPFHub.io
    try:
    dados_cpf = consultar_cpf(cpf_limpo)
    except Exception as e:
    return {"sucesso": False, "erro": str(e), "codigo": "ERRO_API"}

    if not dados_cpf:
    return {
    "sucesso": False,
    "erro": "CPF não encontrado na base de dados",
    "codigo": "CPF_NAO_ENCONTRADO",
    }

    # Verificação 4: Maioridade
    ano_nascimento = dados_cpf.get("year", 0)
    if ano_nascimento:
    idade = datetime.now().year - ano_nascimento
    if idade < 18:
    return {
    "sucesso": False,
    "erro": "Vendedores devem ter pelo menos 18 anos",
    "codigo": "MENOR_IDADE",
    }

    # Verificação 5: Correspondência de nomes
    nome_api = dados_cpf.get("name", "")

    # CPF vs nome informado
    comp_nome = comparar_nomes(nome, nome_api)
    if not comp_nome["corresponde"]:
    return {
    "sucesso": False,
    "erro": "Nome informado não corresponde ao CPF",
    "codigo": "NOME_DIVERGENTE",
    "detalhe": f"Score de similaridade: {comp_nome['score']}",
    }

    # CPF vs titular bancário
    comp_banco = comparar_nomes(nome_titular_banco, nome_api)
    if not comp_banco["corresponde"]:
    return {
    "sucesso": False,
    "erro": "O titular da conta bancária não corresponde ao CPF",
    "codigo": "TITULAR_BANCO_DIVERGENTE",
    "detalhe": (
    "O nome no CPF deve ser idêntico ao titular da conta "
    "para garantir repasses corretos."
    ),
    }

    # Tudo validado -- cria vendedor
    vendedor_id = hashlib.md5(
    f"{cpf_limpo}-{datetime.now().isoformat()}".encode()
    ).hexdigest()[:12]

    vendedor = {
    "id": vendedor_id,
    "cpf": cpf_limpo,
    "nome": dados_cpf.get("name"),
    "nomeUpper": dados_cpf.get("nameUpper"),
    "email": email,
    "telefone": telefone,
    "dataNascimento": dados_cpf.get("birthDate"),
    "genero": dados_cpf.get("gender"),
    "dadosBancarios": {
    "titular": nome_titular_banco,
    "banco": banco,
    "agencia": agencia,
    "conta": conta,
    },
    "categoriaProdutos": categoria_produtos,
    "status": "PENDENTE_APROVACAO",
    "verificacaoCpf": True,
    "scoreNome": comp_nome["score"],
    "scoreBanco": comp_banco["score"],
    "criadoEm": datetime.now().isoformat(),
    "metricas": {
    "totalVendas": 0,
    "avaliacaoMedia": None,
    "reclamacoes": 0,
    "taxaCancelamento": 0,
    },
    }

    vendedores[cpf_limpo] = vendedor

    return {
    "sucesso": True,
    "vendedorId": vendedor_id,
    "nome": dados_cpf.get("name"),
    "status": "PENDENTE_APROVACAO",
    "mensagem": (
    "Inscrição recebida. Sua conta será analisada em até 48 horas."
    ),
    }

def verificar_reincidencia(cpf: str) -> dict:
    """Verifica se o CPF tem histórico de bloqueio em contas anteriores."""
    cpf_limpo = re.sub(r"\D", "", cpf)

    if cpf_limpo in cpfs_banidos:
    return {"reincidente": True, "tipo": "BANIDO_PERMANENTE"}

    vendedor = vendedores.get(cpf_limpo)
    if vendedor and vendedor["status"] == "BLOQUEADO":
    return {"reincidente": True, "tipo": "CONTA_BLOQUEADA"}

    return {"reincidente": False}

# Exemplo de uso
if __name__ == "__main__":
    resultado = inscrever_vendedor(
    cpf="123.456.789-09",
    nome="João da Silva",
    email="joao@loja.com",
    telefone="11999998888",
    nome_titular_banco="João da Silva Santos",
    banco="Banco do Brasil",
    agencia="1234",
    conta="56789-0",
    categoria_produtos="Eletrônicos",
    )
    print(json.dumps(resultado, indent=2, ensure_ascii=False))

Monitoramento contínuo de vendedores

A validação de CPF não termina na inscrição. O acompanhamento contínuo dos vendedores é essencial para manter a qualidade do marketplace.

Indicadores de risco por vendedor

Monitore métricas como taxa de cancelamento, volume de reclamações, tempo médio de envio e taxa de devolução. Vendedores cujas métricas deterioram rapidamente devem ser submetidos a revisão. O CPF vinculado permite que a plataforma mantenha um registro permanente do comportamento de cada vendedor.

Revalidação periódica

Realize revalidações periódicas do CPF dos vendedores ativos. Isso garante que os dados continuam atualizados e que o CPF permanece válido.

Bloqueio e reincidência

Quando um vendedor é bloqueado, o CPF deve ser marcado na lista de impedidos. A API da CPFHub.io retorna os dados cadastrais vinculados ao CPF, permitindo cruzar tentativas de re-cadastro com diferentes e-mails mas o mesmo documento — identificando reincidentes antes que voltem a operar.

Verificação cruzada com dados bancários

A consistência entre o CPF e os dados bancários é fundamental para a segurança financeira do marketplace.

O nome retornado pela API deve corresponder ao titular da conta bancária. Divergências indicam que o vendedor pode estar usando CPF de terceiros ou dados bancários de outra pessoa — ambos sinais de fraude. Essa verificação cruzada previne esquemas em que um fraudador usa o CPF de uma vítima para receber pagamentos em sua própria conta bancária.

Escalabilidade e performance

Para marketplaces com alto volume de inscrições, a validação de CPF via API precisa ser rápida e confiável. A CPFHub.io responde em ~900ms e não bloqueia ao atingir o limite do plano — quando o volume mensal é excedido, cada consulta adicional custa R$0,15, garantindo continuidade operacional sem interrupções.

O plano gratuito com 50 consultas mensais é adequado para marketplaces em fase de validação. O plano Pro a R$149/mês com 1.000 consultas atende marketplaces em crescimento. Para operações maiores, o plano Corporativo é negociado sob consulta.

Perguntas frequentes

Por que comparar o nome do CPF com o titular da conta bancária?

Fraudes de marketplaces frequentemente envolvem o uso do CPF de uma vítima combinado com dados bancários do próprio fraudador. Quando o nome retornado pela API diverge do titular da conta, o sistema sinaliza a inconsistência antes de liberar o cadastro. Essa verificação cruzada é uma das camadas mais eficazes de prevenção, pois o fraudador raramente consegue controlar tanto o CPF da vítima quanto a conta bancária no mesmo nome.

Como tratar vendedores com nomes compostos ou abreviados?

A função comparar_nomes no exemplo usa normalização Unicode, remoção de acentos e análise por partes do nome, calculando um score de similaridade. Vendedores com nomes compostos longos que usam abreviações são aceitos se o primeiro nome, o último sobrenome e pelo menos 60% das partes coincidirem. Ajuste o threshold conforme o perfil do seu público para equilibrar segurança e taxa de aprovação.

O que fazer quando a API retorna erro de timeout durante a inscrição?

O código trata timeouts com requests.exceptions.Timeout e retorna código ERRO_API para o solicitante. A recomendação é apresentar ao vendedor uma mensagem de "tentativa em instantes" e enfileirar a validação para reprocessamento automático — nunca aprovar o cadastro sem a confirmação da API. O timeout de 10 segundos cobre qualquer variação de latência da rede.

Como detectar vendedores banidos que tentam criar novos cadastros?

A função verificar_reincidencia cruza o CPF contra duas listas: cpfs_banidos (bloqueio permanente) e registros com status BLOQUEADO. Como o CPF é único por pessoa física, qualquer tentativa de recadastro com o mesmo documento é identificada imediatamente, independentemente do e-mail, telefone ou dados bancários usados na nova tentativa.

Conclusão

A inscrição de vendedores é o momento mais crítico para a segurança de um marketplace B2C. Um vendedor não verificado que entra na plataforma pode causar danos irreversíveis à reputação e gerar prejuízos financeiros significativos. A validação de CPF via API é o filtro mais eficaz para garantir que cada vendedor é uma pessoa real e identificável — e a verificação cruzada com os dados bancários fecha o principal vetor de fraude de identidade nesse contexto.

Com a CPFHub.io, você implementa esse fluxo completo em menos de 30 minutos, sem precisar gerenciar infraestrutura própria de consulta à Receita Federal. Cadastre-se em cpfhub.io e teste gratuitamente com 50 consultas por mês, sem cartão de crédito.