Dev Data Client

Cliente JavaScript/TypeScript para a API Dev Data - Consulta de CPF.

Instalação

npm install dev-data-client

Uso Rápido

import { findByCpf, findByName, getRandom } from 'dev-data-client';

// Buscar por CPF
const cpfData = await findByCpf('12345678900');
console.log(cpfData.result.nome);

// Buscar por nome
const results = await findByName({ nome: 'maria', page: 1, limit: 10 });
console.log(results.results);
console.log(results.pagination);

// Pessoa aleatória
const random = await getRandom();
console.log(random.result);

Uso com Instância Customizada

import DevDataClient from 'dev-data-client';

const client = new DevDataClient({
  baseUrl: 'https://dev-data.hubgratis.com.br', // opcional
  timeout: 5000, // opcional, padrão 10000ms
});

const data = await client.findByCpf('12345678900');

API

findByCpf(cpf: string)

Busca dados de um CPF específico.

const data = await findByCpf('12345678900');
// ou com formatação
const data = await findByCpf('123.456.789-00');

Retorno:

{
  result: {
    cpf: "12345678900",
    nome: "FULANO DE TAL",
    sexo: "M",
    nasc: "01/01/1990"
  },
  message: "CPF encontrado"
}

findByName(options)

Busca CPFs por nome (busca parcial).

const data = await findByName({
  nome: 'maria',      // obrigatório
  page: 1,            // opcional, padrão 1
  limit: 10           // opcional, padrão 10, máx 100
});

Retorno:

{
  results: [
    { cpf: "123...", nome: "MARIA SILVA", sexo: "F", nasc: "..." }
  ],
  message: "Resultados para: MARIA",
  pagination: {
    page: 1,
    limit: 10,
    total: 150,
    totalPages: 15,
    hasNext: true,
    hasPrev: false
  }
}

getRandom()

Obtém uma pessoa aleatória do banco.

const data = await getRandom();

health()

Verifica o status da API.

const status = await health();
console.log(status.result.status); // 'online'

Tratamento de Erros

import { findByCpf, DevDataError } from 'dev-data-client';

try {
  const data = await findByCpf('12345678900');
} catch (error) {
  if (error instanceof DevDataError) {
    console.log(error.message);    // "CPF não encontrado"
    console.log(error.code);       // "NOT_FOUND"
    console.log(error.statusCode); // 404
  }
}

Códigos de Erro

| Código | Status | Descrição | |--------|--------|-----------| | BAD_REQUEST | 400 | Requisição inválida | | NOT_FOUND | 404 | CPF ou recurso não encontrado | | RATE_LIMIT | 429 | Limite de requisições excedido | | INTERNAL_ERROR | 500 | Erro interno do servidor | | TIMEOUT | 408 | Timeout na requisição | | CONNECTION_ERROR | 0 | Erro de conexão |

TypeScript

O pacote inclui tipagens completas:

import type { CpfData, Pagination, SearchOptions } from 'dev-data-client';

Limites da API

• 100 requisições por minuto por IP
• 100 resultados por página (máximo)

Licença

MIT