CPFHub.io
Começar grátis

Casos de Uso

Exemplos práticos de como integrar a API do CPFHub.io em cenários reais.

Preenchimento automático no cadastro

O caso mais comum: o usuário digita o CPF e o formulário preenche o nome automaticamente, reduzindo atrito e erros de digitação.

TypeScript
async function preencherNome(cpf: string) {
  const resultado = await client.lookup(cpf)
  if (resultado.success) {
    document.getElementById('nome').value = resultado.data.name
  }
}
✦

UX: mostre o nome para confirmação

Exiba o nome retornado para o usuário confirmar antes de prosseguir. Isso aumenta a confiança e evita erros caso o CPF seja de outra pessoa.

KYC e onboarding

Verificar se o CPF existe e se o nome fornecido pelo usuário confere com o cadastro - etapa essencial em fluxos de abertura de conta, crédito ou contratação.

TypeScript
async function validarIdentidade(cpf: string, nomeInformado: string): Promise<boolean> {
  const resultado = await client.lookup(cpf)

  if (!resultado.success) return false

  const nomeAPI = resultado.data.nameUpper
  const nomeUsuario = nomeInformado.toUpperCase().trim()

  // Comparação tolerante a espaços extras e variações
  return nomeAPI.includes(nomeUsuario.split(' ')[0])
}
Python
def validar_identidade(cpf: str, nome_informado: str) -> bool:
    resultado = client.lookup(cpf)
    if not resultado.success:
        return False
    primeiro_nome = nome_informado.upper().strip().split()[0]
    return primeiro_nome in resultado.data.name_upper

Validação antes de criar conta

Rejeitar CPFs inválidos ou inexistentes antes de persistir o usuário no banco - evita cadastros fraudulentos e dados inconsistentes.

TypeScript
import { CPFHub, CPFHubError } from '@cpfhub/sdk'

const client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })

export async function validarCPFNoCadastro(cpf: string) {
  try {
    const resultado = await client.lookup(cpf)
    return { valido: true, nome: resultado.data.name }
  } catch (err) {
    if (err instanceof CPFHubError) {
      if (err.code === 'CPF_NOT_FOUND') {
        return { valido: false, motivo: 'CPF não encontrado na base de dados' }
      }
      if (err.code === 'INVALID_CPF_DIGITS') {
        return { valido: false, motivo: 'CPF com dígitos verificadores inválidos' }
      }
    }
    throw err
  }
}
⚠

CPF_NOT_FOUND não consome crédito

Quando o CPF não existe na base, a API retorna 404 com código CPF_NOT_FOUND e não desconta créditos. Ideal para validar em tempo real enquanto o usuário digita.

Prevenção de fraudes

Em operações sensíveis (pagamentos, saques, contratos), cruzar os dados do CPF com o que o usuário declarou antes de liberar a transação.

TypeScript
interface ResultadoAntifraude {
  aprovado: boolean
  confianca: 'alta' | 'media' | 'baixa'
  motivo?: string
}

async function verificarAntifraude(
  cpf: string,
  nomeFornecido: string,
  dataFornecida: string // formato: DD/MM/YYYY
): Promise<ResultadoAntifraude> {
  const { data } = await client.lookup(cpf)

  const nomeConfere = data.nameUpper.includes(nomeFornecido.toUpperCase().split(' ')[0])
  const dataConfere = data.birthDate === dataFornecida

  if (nomeConfere && dataConfere) {
    return { aprovado: true, confianca: 'alta' }
  }
  if (nomeConfere || dataConfere) {
    return { aprovado: true, confianca: 'media' }
  }
  return { aprovado: false, confianca: 'baixa', motivo: 'Dados não conferem com o CPF' }
}

Compliance e concessão de crédito

Antes de aprovar um limite de crédito, verificar a validade do CPF e cruzar com os dados declarados pelo solicitante.

TypeScript
async function analisarSolicitacaoCredito(solicitacao: {
  cpf: string
  nomeCompleto: string
  dataNascimento: string
}) {
  const dados = await client.lookup(solicitacao.cpf)

  return {
    cpfValido: true,
    nomeConfere: dados.data.nameUpper === solicitacao.nomeCompleto.toUpperCase(),
    dataNascimentoConfere: dados.data.birthDate === solicitacao.dataNascimento,
    dadosOficiais: {
      nome: dados.data.name,
      genero: dados.data.gender,
      nascimento: dados.data.birthDate,
    },
  }
}

Enriquecimento de base de dados

Percorrer uma base existente de CPFs para preencher nomes e datas de nascimento faltantes, respeitando o rate limit do plano.

TypeScript
import pLimit from 'p-limit'

async function enriquecerBase(cpfs: string[]) {
  const limit = pLimit(5) // máx 5 requisições simultâneas

  const resultados = await Promise.all(
    cpfs.map(cpf =>
      limit(async () => {
        try {
          const { data } = await client.lookup(cpf)
          return { cpf, nome: data.name, nascimento: data.birthDate, status: 'ok' }
        } catch {
          return { cpf, status: 'nao_encontrado' }
        }
      })
    )
  )

  return resultados
}
✦

Rate limit e planos

Cada plano tem um limite de requisições por segundo. Para processamentos em lote, use concorrência controlada (ex: p-limit) e implemente retry com backoff exponencial para erros 429. Veja Códigos de Erro & Tratamento.

Atualizado em 12 de maio de 2026