Validação de CPF para emissão de garantia estendida em e-commerce

Para emitir garantias estendidas em e-commerce com segurança, o CPF do comprador precisa ser validado em tempo real via API antes da geração do certificado. Sem essa verificação, a seguradora pode recusar o sinistro por inconsistência de dados — e a reclamação recai sobre a loja. A validação resolve o problema na origem, durante o checkout.

Introdução

A garantia estendida é um dos serviços complementares mais rentáveis no e-commerce brasileiro. Ela gera receita adicional para a loja e oferece segurança ao consumidor. No entanto, o processo de emissão dessa garantia exige que o CPF do comprador seja válido e corresponda a uma pessoa real — caso contrário, a seguradora pode recusar o sinistro, gerando conflitos e prejuízos para todas as partes.

Por que validar CPF na garantia estendida

Requisitos das seguradoras

A maioria das seguradoras que operam garantia estendida exige que o certificado seja vinculado a um CPF válido. Quando o consumidor aciona o sinistro, a seguradora verifica se o CPF do solicitante corresponde ao CPF do certificado. Um CPF inválido ou inconsistente resulta em recusa do sinistro — e a reclamação recai sobre o e-commerce.

Fraudes comuns

Existem padrões de fraude específicos em garantias estendidas. Compras com CPFs de terceiros que depois tentam transferir a garantia. Uso de CPFs inválidos que passam na validação estrutural mas não correspondem a pessoas reais. Tentativas de acionar a garantia com dados divergentes dos registrados no certificado.

Obrigações legais

O Código de Defesa do Consumidor e as normas da SUSEP exigem que as garantias estendidas sejam emitidas com dados corretos do beneficiário. A LGPD, por sua vez, exige que o tratamento de dados pessoais — incluindo CPF — seja feito com base legal adequada e com medidas de segurança.

Fluxo de emissão com validação

O processo de emissão de garantia estendida com validação de CPF segue um fluxo estruturado.

Primeiro, o cliente adiciona a garantia estendida ao carrinho junto com o produto. No checkout, o sistema solicita o CPF do beneficiário. O CPF é validado estruturalmente e consultado na API da CPFHub.io. Se o CPF for válido e corresponder a uma pessoa real, o certificado é gerado com os dados retornados pela API. Caso contrário, o sistema exibe uma mensagem de erro e solicita a correção antes de prosseguir.

Implementação em Python

O exemplo abaixo demonstra um serviço de emissão de garantia estendida com validação de CPF integrada.

import requests
import re
from datetime import datetime, timedelta
from dataclasses import dataclass
from typing import Optional
import hashlib
import json

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

@dataclass
class CertificadoGarantia:
    numero: str
    cpf_beneficiario: str
    nome_beneficiario: str
    data_nascimento: str
    produto: str
    valor_produto: float
    valor_garantia: float
    data_emissao: str
    data_validade: str
    status: str

def validar_cpf_estrutural(cpf: str) -> bool:
    """Valida os dígitos verificadores do CPF."""
    cpf = re.sub(r"\D", "", cpf)
    if len(cpf) != 11 or cpf == cpf[0] * 11:
    return False

    for i in range(9, 11):
    soma = sum(int(cpf[j]) * ((i + 1) - j) for j in range(i))
    digito = (soma * 10 % 11) % 10
    if int(cpf[i]) != digito:
    return False
    return True

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("Tempo limite excedido na consulta de CPF")
    except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    if status == 401:
    raise Exception("Chave de API inválida")
    if status == 404:
    return None
    raise Exception(f"Erro HTTP {status} na consulta de CPF")
    except requests.exceptions.RequestException:
    raise Exception("Erro de conexão com a API de CPF")

def gerar_numero_certificado(cpf: str, produto: str) -> str:
    """Gera um número único para o certificado de garantia."""
    dados = f"{cpf}-{produto}-{datetime.now().isoformat()}"
    hash_hex = hashlib.sha256(dados.encode()).hexdigest()[:12]
    return f"GE-{hash_hex.upper()}"

def calcular_valor_garantia(valor_produto: float, meses: int) -> float:
    """Calcula o valor da garantia estendida com base no produto."""
    # Taxa base: 8% do valor do produto por 12 meses
    taxa_base = 0.08
    fator_periodo = meses / 12
    return round(valor_produto * taxa_base * fator_periodo, 2)

def emitir_garantia_estendida(
    cpf: str,
    produto: str,
    valor_produto: float,
    meses_garantia: int = 12,
) -> dict:
    """Emite certificado de garantia estendida após validação do CPF."""

    # Passo 1 -- Validação estrutural
    if not validar_cpf_estrutural(cpf):
    return {
    "sucesso": False,
    "erro": "CPF inválido. Verifique os dígitos informados.",
    }

    # Passo 2 -- Consulta à API CPFHub.io
    try:
    dados_cpf = consultar_cpf(cpf)
    except Exception as e:
    return {"sucesso": False, "erro": str(e)}

    if not dados_cpf:
    return {
    "sucesso": False,
    "erro": "CPF não encontrado. Não é possível emitir a garantia.",
    }

    # Passo 3 -- Verificação de maioridade
    ano_nascimento = dados_cpf.get("year", 0)
    idade = datetime.now().year - ano_nascimento
    if idade < 18:
    return {
    "sucesso": False,
    "erro": "Garantia estendida disponível apenas para maiores de 18 anos.",
    }

    # Passo 4 -- Cálculo e emissão
    cpf_limpo = re.sub(r"\D", "", cpf)
    valor_garantia = calcular_valor_garantia(valor_produto, meses_garantia)
    data_emissao = datetime.now()
    data_validade = data_emissao + timedelta(days=meses_garantia * 30)

    certificado = CertificadoGarantia(
    numero=gerar_numero_certificado(cpf_limpo, produto),
    cpf_beneficiario=cpf_limpo,
    nome_beneficiario=dados_cpf.get("name", ""),
    data_nascimento=dados_cpf.get("birthDate", ""),
    produto=produto,
    valor_produto=valor_produto,
    valor_garantia=valor_garantia,
    data_emissao=data_emissao.strftime("%d/%m/%Y"),
    data_validade=data_validade.strftime("%d/%m/%Y"),
    status="ATIVO",
    )

    return {
    "sucesso": True,
    "certificado": {
    "numero": certificado.numero,
    "beneficiario": certificado.nome_beneficiario,
    "produto": certificado.produto,
    "valorProduto": f"R$ {certificado.valor_produto:.2f}",
    "valorGarantia": f"R$ {certificado.valor_garantia:.2f}",
    "vigencia": f"{certificado.data_emissao} a {certificado.data_validade}",
    "status": certificado.status,
    },
    }

# Exemplo de uso
if __name__ == "__main__":
    resultado = emitir_garantia_estendida(
    cpf="123.456.789-09",
    produto="Smartphone Galaxy S24 Ultra",
    valor_produto=7499.00,
    meses_garantia=24,
    )
    print(json.dumps(resultado, indent=2, ensure_ascii=False))

Validação no acionamento do sinistro

A validação de CPF não deve ocorrer apenas na emissão. Quando o consumidor aciona a garantia, o sistema precisa confirmar a identidade do solicitante.

def acionar_garantia(
    numero_certificado: str,
    cpf_solicitante: str,
    descricao_problema: str,
    certificados_emitidos: dict,
) -> dict:
    """Valida o CPF do solicitante contra o certificado."""

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

    # Busca o certificado
    certificado = certificados_emitidos.get(numero_certificado)
    if not certificado:
    return {"sucesso": False, "erro": "Certificado não encontrado"}

    # Verifica se o CPF corresponde
    if certificado["cpf_beneficiario"] != cpf_limpo:
    return {
    "sucesso": False,
    "erro": "CPF do solicitante não corresponde ao beneficiário",
    }

    # Consulta a API para confirmar que o CPF ainda é válido
    try:
    dados_cpf = consultar_cpf(cpf_limpo)
    if not dados_cpf:
    return {
    "sucesso": False,
    "erro": "CPF não encontrado na base de dados",
    }
    except Exception as e:
    return {"sucesso": False, "erro": f"Erro na validação: {str(e)}"}

    return {
    "sucesso": True,
    "mensagem": "Sinistro registrado com sucesso",
    "protocolo": f"SIN-{numero_certificado}-{datetime.now().strftime('%Y%m%d')}",
    "beneficiario": dados_cpf.get("name"),
    }

Integração com seguradoras

A maioria das seguradoras parceiras aceita dados no formato JSON ou XML para a emissão eletrônica de certificados. Os dados retornados pela API da CPFHub.io — nome completo, CPF e data de nascimento — são suficientes para preencher os campos obrigatórios do certificado sem etapas manuais adicionais.

Dados obrigatórios do certificado

O certificado de garantia estendida deve conter, no mínimo, o número do certificado, o CPF e nome completo do beneficiário, a descrição do produto coberto, o valor do produto e da garantia, as datas de emissão e validade, e as condições gerais da cobertura.

Reconciliação mensal

Recomenda-se uma rotina mensal de reconciliação entre os certificados emitidos pelo e-commerce e os registros da seguradora. Discrepâncias nos dados de CPF ou nome devem ser investigadas imediatamente.

Boas práticas para LGPD

O tratamento de CPF no contexto de garantia estendida tem base legal no cumprimento de obrigação contratual (Art. 7, V da LGPD). Ainda assim, é importante observar algumas práticas.

Informe ao consumidor, de forma clara, que o CPF será consultado para validação e vinculado ao certificado de garantia. Armazene apenas os dados necessários — CPF, nome e data de nascimento. Descarte dados complementares que não sejam relevantes para o certificado. Implemente controles de acesso para que apenas sistemas e funcionários autorizados possam consultar os dados dos certificados. Defina um prazo de retenção compatível com o período de vigência da garantia, acrescido do prazo prescricional.

Performance e considerações de produção

A API da CPFHub.io retorna resposta em aproximadamente 900ms, com SLA de 99,9% de disponibilidade — latência compatível com fluxos de checkout sem prejudicar a conversão.

Para e-commerces com alto volume de vendas, o plano Pro a R$ 149/mês oferece 1.000 consultas. Considerando que nem toda venda inclui garantia estendida, esse volume atende a maioria das operações de médio porte.

Perguntas frequentes

O que acontece se o CPF for inválido durante a emissão da garantia?

O sistema bloqueia a emissão do certificado e exibe uma mensagem de erro antes de qualquer cobrança ser processada. O consumidor é solicitado a corrigir o CPF antes de concluir o checkout. Isso evita certificados com dados incorretos e reduz o risco de recusa de sinistro pela seguradora.

A API CPFHub.io bloqueia quando o limite de consultas é atingido?

Não. A API não bloqueia em nenhum cenário. Quando o limite do plano é atingido, cada consulta adicional é cobrada a R$0,15. O plano gratuito inclui 50 consultas por mês sem cartão de crédito, ideal para lojas que estão começando a oferecer garantia estendida.

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 é um passo essencial na emissão de garantias estendidas em e-commerce. Ela protege o consumidor contra problemas no acionamento do sinistro, protege o lojista contra fraudes e atende às exigências das seguradoras parceiras. Com a API da CPFHub.io, a verificação acontece em tempo real durante o checkout, sem atrito para o usuário e com os dados que a seguradora exige.

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