SDK Node.js / TypeScript

SDK oficial com suporte completo a TypeScript, tratamento de erros tipado e compatível com Node.js 18+.

Instalação

bash

npm install @cpfhub/sdk

Requerimentos: Node.js 18+ (usa fetch nativo)

Inicialização

TypeScript

import { CPFHub } from '@cpfhub/sdk'

const client = new CPFHub({
  apiKey: process.env.CPFHUB_API_KEY,
  // timeout: 5000,  // opcional, padrão: 10000ms
})

Opções do construtor

Opção	Tipo	Padrão	Descrição
`apiKey`	`string`	-	Sua API Key (obrigatório)
`timeout`	`number`	`10000`	Timeout em ms
`baseUrl`	`string`	`https://api.cpfhub.io`	URL base da API

Métodos

`client.lookup(cpf)`

Consulta um CPF e retorna os dados de identidade.

TypeScript

const result = await client.lookup('12345678909')

Parâmetros:

Parâmetro	Tipo	Descrição
`cpf`	`string`	CPF com ou sem formatação

Retorno: Promise<CPFHubResult>

TypeScript

interface CPFHubResult {
  success: boolean
  data: {
    cpf: string
    name: string
    nameUpper: string
    gender: 'M' | 'F'
    birthDate: string    // "DD/MM/AAAA"
    day: number
    month: number
    year: number
  }
}

Tratamento de erros

O SDK lança CPFHubError para todos os erros da API:

TypeScript

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

try {
  const result = await client.lookup('12345678909')
} catch (err) {
  if (err instanceof CPFHubError) {
    console.log(err.code)       // "CPF_NOT_FOUND"
    console.log(err.message)    // "CPF not found in our database"
    console.log(err.statusCode) // 404
  }
}

Códigos de erro

`err.code`	`err.statusCode`	Descrição
`CPF_NOT_FOUND`	`404`	CPF não encontrado (sem consumo de crédito)
`INVALID_CPF_FORMAT`	`400`	Formato inválido
`INVALID_CPF_DIGITS`	`422`	Dígitos verificadores inválidos
`MISSING_API_KEY`	`401`	API Key ausente
`INVALID_API_KEY`	`401`	API Key inválida
`RATE_LIMIT_EXCEEDED`	`429`	Limite de taxa excedido
`INSUFFICIENT_CREDITS`	`403`	Sem créditos disponíveis

Exemplos de integração

Next.js API Route

TypeScript

// app/api/cpf/[cpf]/route.ts
import { CPFHub, CPFHubError } from '@cpfhub/sdk'
import { NextResponse } from 'next/server'

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

export async function GET(
  request: Request,
  { params }: { params: { cpf: string } }
) {
  try {
    const result = await client.lookup(params.cpf)
    return NextResponse.json(result.data)
  } catch (err) {
    if (err instanceof CPFHubError) {
      return NextResponse.json(
        { error: err.code },
        { status: err.statusCode }
      )
    }
    return NextResponse.json({ error: 'INTERNAL_ERROR' }, { status: 500 })
  }
}

Validação em formulário (com Zod)

TypeScript

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

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

const schema = z.object({
  cpf: z.string().regex(/^\d{11}$/, 'CPF deve ter 11 dígitos'),
})

async function validateUser(data: unknown) {
  const { cpf } = schema.parse(data)

  try {
    const result = await client.lookup(cpf)
    return { valid: true, name: result.data.name }
  } catch (err) {
    if (err instanceof CPFHubError && err.code === 'CPF_NOT_FOUND') {
      return { valid: false, name: null }
    }
    throw err
  }
}

Repositório e suporte

github.com/cpfhub/cpfhub-node - código-fonte, issues e contribuições
npm: @cpfhub/sdk - versões e changelog

Atualizado em 12 de maio de 2026