Marketplaces podem usar a API de CPF da CPFHub.io como primeiro passo para implementar limites de crédito seguros: validar o CPF do comprador garante que cada linha de crédito está vinculada a uma pessoa real, fornece dados demográficos para scoring inicial e cria a chave de identificação para construir o histórico interno de pagamentos. O plano gratuito da CPFHub.io oferece 50 consultas mensais sem cartão de crédito para começar imediatamente.
Introdução
Marketplaces que oferecem crédito aos compradores -- seja na forma de "compre agora, pague depois", parcelamento próprio ou saldo virtual -- enfrentam um desafio fundamental: como definir limites de crédito seguros sem ter acesso a um bureau de crédito completo? A resposta começa com a validação de CPF.
O CPF é o identificador que conecta uma pessoa física ao sistema financeiro brasileiro. Validar o CPF via API é o primeiro passo para construir um perfil de crédito dentro do marketplace.
O papel do CPF nos limites de crédito
Identificação única
O CPF garante que cada linha de crédito está vinculada a uma pessoa real e única. Sem essa verificação, um fraudador poderia criar múltiplas contas e acumular crédito em todas elas, causando prejuízo quando não pagar.
Dados demográficos para scoring
A API da CPFHub.io retorna nome completo, gênero e data de nascimento do titular — dados que permitem calcular a idade e aplicar critérios de scoring iniciais com base no perfil demográfico, antes mesmo de consultar bureaus externos.
Base para histórico interno
Com o CPF como chave, o marketplace pode construir um histórico de comportamento de pagamento ao longo do tempo: pontualidade, valores pagos, contestações. Esse histórico interno se torna cada vez mais valioso para ajustar os limites de crédito.
Implementação em Python
O exemplo a seguir demonstra um sistema de limites de crédito com validação de CPF.
import requests
import re
from datetime import datetime, timedelta
from typing import Optional
from dataclasses import dataclass, field
import json
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
contas_credito = {} # cpf -> ContaCredito
historico_pagamentos = {} # cpf -> [pagamentos]
@dataclass
class ContaCredito:
cpf: str
nome: str
data_nascimento: str
genero: str
limite_total: float
limite_disponivel: float
nivel: str
score_interno: float
total_compras: int = 0
total_pago: float = 0.0
total_atrasado: int = 0
criado_em: str = ""
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 calcular_limite_inicial(dados_cpf: dict, historico_plataforma: dict) -> dict:
"""Calcula o limite de crédito inicial com base nos dados do CPF e histórico."""
# Limite base
limite_base = 200.0 # R$ 200 para novos usuários
score = 50.0 # Score inicial médio
fatores = []
# Fator 1: Idade
ano_nascimento = dados_cpf.get("year", 0)
if ano_nascimento:
idade = datetime.now().year - ano_nascimento
if idade < 18:
return {
"limite": 0,
"motivo": "Menor de idade -- crédito não disponível",
}
if 25 <= idade <= 55:
score += 10
fatores.append(f"Faixa etária favorável ({idade} anos): +10")
elif 18 <= idade < 25:
score += 5
fatores.append(f"Jovem adulto ({idade} anos): +5")
elif idade > 55:
score += 8
fatores.append(f"Faixa etária madura ({idade} anos): +8")
# Fator 2: Histórico na plataforma
if historico_plataforma:
total_compras = historico_plataforma.get("total_compras", 0)
total_gasto = historico_plataforma.get("total_gasto", 0)
if total_compras >= 10:
score += 20
fatores.append(f"Cliente recorrente ({total_compras} compras): +20")
limite_base = 500.0
elif total_compras >= 5:
score += 10
fatores.append(f"Cliente ativo ({total_compras} compras): +10")
limite_base = 350.0
if total_gasto > 5000:
score += 15
fatores.append(f"Alto volume (R$ {total_gasto:.2f}): +15")
limite_base = 800.0
# Fator 3: Ausência de problemas anteriores
problemas = historico_plataforma.get("disputas", 0) if historico_plataforma else 0
if problemas == 0:
score += 10
fatores.append("Sem disputas registradas: +10")
elif problemas > 2:
score -= 20
fatores.append(f"Múltiplas disputas ({problemas}): -20")
# Calcula limite final
score = max(0, min(100, score))
multiplicador = score / 50 # Score 50 = multiplicador 1x
limite_final = round(limite_base * multiplicador, 2)
# Limites por nível
if score >= 80:
nivel = "PREMIUM"
limite_maximo = 5000.0
elif score >= 60:
nivel = "PADRAO"
limite_maximo = 2000.0
elif score >= 40:
nivel = "BASICO"
limite_maximo = 500.0
else:
nivel = "RESTRITO"
limite_maximo = 100.0
limite_final = min(limite_final, limite_maximo)
return {
"limite": limite_final,
"score": score,
"nivel": nivel,
"fatores": fatores,
}
def abrir_conta_credito(cpf: str, historico_plataforma: dict = None) -> dict:
"""Abre uma conta de crédito após validação de CPF."""
cpf_limpo = re.sub(r"\D", "", cpf)
# Verifica se já existe
if cpf_limpo in contas_credito:
conta = contas_credito[cpf_limpo]
return {
"sucesso": True,
"existente": True,
"limite": conta.limite_total,
"disponivel": conta.limite_disponivel,
"nivel": conta.nivel,
}
# Valida CPF
try:
dados = consultar_cpf(cpf_limpo)
except Exception as e:
return {"sucesso": False, "erro": str(e)}
if not dados:
return {"sucesso": False, "erro": "CPF não encontrado"}
# Calcula limite
resultado_limite = calcular_limite_inicial(
dados, historico_plataforma or {}
)
if resultado_limite["limite"] == 0:
return {
"sucesso": False,
"erro": resultado_limite.get("motivo", "Crédito não aprovado"),
}
conta = ContaCredito(
cpf=cpf_limpo,
nome=dados.get("name", ""),
data_nascimento=dados.get("birthDate", ""),
genero=dados.get("gender", ""),
limite_total=resultado_limite["limite"],
limite_disponivel=resultado_limite["limite"],
nivel=resultado_limite["nivel"],
score_interno=resultado_limite["score"],
criado_em=datetime.now().isoformat(),
)
contas_credito[cpf_limpo] = conta
return {
"sucesso": True,
"existente": False,
"titular": dados.get("name"),
"limite": resultado_limite["limite"],
"nivel": resultado_limite["nivel"],
"score": resultado_limite["score"],
"fatores": resultado_limite["fatores"],
}
def usar_credito(cpf: str, valor: float, descricao: str) -> dict:
"""Realiza uma compra usando o crédito do marketplace."""
cpf_limpo = re.sub(r"\D", "", cpf)
conta = contas_credito.get(cpf_limpo)
if not conta:
return {"sucesso": False, "erro": "Conta de crédito não encontrada"}
if valor > conta.limite_disponivel:
return {
"sucesso": False,
"erro": f"Limite insuficiente. Disponível: R$ {conta.limite_disponivel:.2f}",
}
conta.limite_disponivel -= valor
conta.total_compras += 1
# Registra no histórico
if cpf_limpo not in historico_pagamentos:
historico_pagamentos[cpf_limpo] = []
historico_pagamentos[cpf_limpo].append({
"tipo": "COMPRA",
"valor": valor,
"descricao": descricao,
"vencimento": (datetime.now() + timedelta(days=30)).isoformat(),
"status": "PENDENTE",
"data": datetime.now().isoformat(),
})
return {
"sucesso": True,
"valorUtilizado": valor,
"limiteDisponivel": conta.limite_disponivel,
"limiteTotal": conta.limite_total,
}
# Exemplo de uso
if __name__ == "__main__":
# Novo cliente sem histórico
print("--- Novo cliente ---")
r1 = abrir_conta_credito("123.456.789-09")
print(json.dumps(r1, indent=2, ensure_ascii=False))
# Cliente com histórico
print("\n--- Cliente com histórico ---")
historico = {
"total_compras": 15,
"total_gasto": 7500.0,
"disputas": 0,
}
r2 = abrir_conta_credito("987.654.321-00", historico)
print(json.dumps(r2, indent=2, ensure_ascii=False))
# Usar crédito
if r2.get("sucesso"):
print("\n--- Usar crédito ---")
r3 = usar_credito("98765432100", 450.00, "Compra de eletrônico")
print(json.dumps(r3, indent=2, ensure_ascii=False))
Evolução dinâmica dos limites
Os limites de crédito não devem ser estáticos. Com o CPF como chave, o marketplace pode ajustar os limites ao longo do tempo com base no comportamento real do usuário.
Aumento automático
Clientes que pagam em dia consistentemente devem ter seus limites aumentados periodicamente. Uma regra comum é aumentar o limite em 20% a cada 3 meses sem atrasos.
Redução por inadimplência
Pagamentos atrasados devem resultar em redução do limite. Um atraso superior a 30 dias pode reduzir o limite em 50%. Dois atrasos consecutivos podem resultar no bloqueio da conta de crédito.
Revisão por evento
Certos eventos devem acionar uma revisão do limite: disputa de chargeback, alteração de dados cadastrais ou inatividade prolongada seguida de compra de alto valor.
Prevenção de fraude no crédito
A validação de CPF é a primeira linha de defesa contra fraude em crédito de marketplace.
Um fraudador que tenta abrir múltiplas contas de crédito usando CPFs diferentes terá cada CPF validado individualmente. Se usar CPFs de terceiros, a verificação de nome detecta a inconsistência. Se criar contas com CPFs válidos mas de pessoas que não são clientes reais, o histórico interno vazio resultará em limites baixos, reduzindo o potencial de prejuízo.
Além disso, a análise de padrões por CPF permite detectar fraudes coordenadas -- como múltiplos CPFs que sempre compram os mesmos produtos e enviam para os mesmos endereços.
Considerações regulatórias
Oferecer crédito no marketplace pode sujeitar a plataforma a regulamentações do Banco Central do Brasil, dependendo do modelo adotado. O uso do CPF como identificador é obrigatório em operações de crédito reguladas. A CPFHub.io fornece a camada de identificação necessária para cumprir essa exigência, com respostas em cerca de 900ms e disponibilidade compatível com operações em produção.
É importante consultar assessoria jurídica para garantir que o modelo de crédito do marketplace está em conformidade com as normas aplicáveis.
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 em cerca 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
Implementar limites de crédito em marketplaces começa com uma base sólida de identificação -- e no Brasil, essa base é o CPF. A validação via API da CPFHub.io garante que cada conta de crédito está vinculada a uma pessoa real, fornece os dados demográficos para o scoring inicial e cria a chave que sustenta o histórico interno de pagamentos.
Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à 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.
