Como validar CPF com Node.js e a API SmartCPF

/**
 * Valida CPF usando a API SmartCPF v2
 * Documentação: https://api.smartcpf.com.br/docs
 */

const API_BASE = 'https://api.smartcpf.com.br/v2';
const API_KEY = process.env.SMARTCPf_API_KEY || 'SUA_API_KEY';

/**
 * Remove formatação do CPF (pontos, hífen, espaços)
 * @param {string} cpf - CPF com ou sem máscara
 * @returns {string} Apenas dígitos
 */
function normalizarCpf(cpf) {
  return cpf.replace(/\D/g, '');
}

/**
 * Consulta CPF na API SmartCPF
 * @param {string} cpf - CPF a consultar (com ou sem máscara)
 * @param {string} pkg - Pacote de dados (padrão: 'basic')
 * @returns {Promise<Object>} Resposta parseada da API
 */
async function consultarCpf(cpf, pkg = 'basic') {
  const cpfLimpo = normalizarCpf(cpf);
  
  if (cpfLimpo.length !== 11) {
    throw new Error('CPF deve conter 11 dígitos numéricos');
  }

  const url = `${API_BASE}/individuals/${cpfLimpo}?package=${encodeURIComponent(pkg)}`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'X-API-KEY': API_KEY,
      'Accept': 'application/json',
      'User-Agent': 'smartcpf-nodejs-exemplo/1.0'
    },
    // Timeout de 10s para evitar travamentos
    signal: AbortSignal.timeout(10_000)
  });

  // A API sempre retorna 200 para consultas processadas; erros de negócio vêm no body
  if (!response.ok) {
    const errBody = await response.text().catch(() => '');
    throw new Error(`HTTP ${response.status}: ${errBody || response.statusText}`);
  }

  const data = await response.json();

  // Estrutura padrão de resposta da SmartCPF
  if (!data.success) {
    const msgs = (data.errors || []).map(e => e.message || e).join('; ');
    throw new Error(`API error: ${msgs || 'Falha desconhecida'}`);
  }

  return data;
}

/**
 * Exibe resultado de forma legível
 */
function exibirResultado(data) {
  const meta = data.meta;
  const result = data.result;

  console.log('\n=== METADADOS DA CONSULTA ===');
  console.log(`ConsultId: ${meta.consultId}`);
  console.log(`Tipo: ${meta.searchType}`);
  console.log(`Usuário: ${meta.user}`);
  console.log(`Mensagem: ${meta.message}`);
  console.log(`IP origem: ${meta.ip}`);
  console.log(`Versão API: ${meta.apiVersion}`);
  console.log(`Data: ${meta.date}`);
  console.log(`Latência: ${meta.executionTimeMs} ms`);
  console.log(`Saldo restante: ${meta.balance} créditos`);

  if (!result || Object.keys(result).length === 0) {
    console.log('\n--- CPF não encontrado nas bases ---');
    return;
  }

  console.log('\n=== DADOS DO TITULAR ===');
  console.log(`CPF: ${result.cpf}`);
  console.log(`Nome: ${result.name}`);
  console.log(`Nascimento: ${result.birthDate} (${result.age} anos)`);
  console.log(`Mãe: ${result.motherName}`);
  console.log(`Gênero: ${result.gender}`);
  console.log(`Situação: ${result.status}`);

  if (result.emails?.length) {
    console.log(`E-mails: ${result.emails.join(', ')}`);
  }

  if (result.phones?.length) {
    console.log('Telefones:');
    result.phones.forEach((p, i) => {
      const tags = [];
      if (p.blockedTelemarketing) tags.push('bloqueado telemarketing');
      if (p.whatsapp) tags.push('WhatsApp');
      const tagStr = tags.length ? ` [${tags.join(', ')}]` : '';
      console.log(`  ${i + 1}. ${p.number} (${p.type}, ${p.operator})${tagStr}`);
    });
  }

  if (result.addresses?.length) {
    console.log('Endereços:');
    result.addresses.forEach((a, i) => {
      console.log(`  ${i + 1}. ${a.street}, ${a.number} - ${a.neighborhood}, ${a.city}/${a.state} - ${a.zipCode}`);
    });
  }
}

/**
 * Função principal - uso via linha de comando
 */
async function main() {
  const cpfArg = process.argv[2];

  if (!cpfArg) {
    console.error('Uso: node validar-cpf.js <CPF> [package]');
    console.error('Exemplo: node validar-cpf.js 111.111.111-11 basic');
    process.exit(1);
  }

  const pkg = process.argv[3] || 'basic';

  try {
    console.log(`Consultando CPF ${cpfArg} (package: ${pkg})...`);
    const data = await consultarCpf(cpfArg, pkg);
    exibirResultado(data);
  } catch (err) {
    console.error('\n❌ Erro:', err.message);
    process.exit(1);
  }
}

// Executa se chamado diretamente
if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

export { consultarCpf, normalizarCpf, exibirResultado };

{
  "meta": {
    "searchType": "CPF G",
    "consultId": "550e8400-e29b-41d4-a716-446655440000",
    "user": "Fulano de Tal",
    "message": "CPF encontrado com sucesso",
    "ip": "127.0.0.1",
    "success": true,
    "apiVersion": "v2",
    "date": "2026-01-15T14:32:10.123Z",
    "executionTimeMs": 74.1,
    "balance": 9.77
  },
  "result": {
    "cpf": "111.111.111-11",
    "name": "João da Silva",
    "birthDate": "10/09/1992",
    "age": 33,
    "motherName": "Maria da Silva",
    "gender": "M",
    "status": "Regular",
    "emails": ["[email protected]"],
    "phones": [
      {
        "number": "(55) 99999-9999",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": false
      }
    ],
    "addresses": []
  },
  "success": true,
  "errors": []
}