CPFHub.io

SDK Dart / Flutter

SDK oficial para Dart 3.0+ e Flutter. Funciona em aplicações Flutter mobile, web e desktop, e em servidores Dart.

Instalação

bash
dart pub add cpfhub

Ou para projetos Flutter:

bash
flutter pub add cpfhub

Requerimentos: Dart 3.0+ / Flutter 3.10+

Inicialização

Dart
import 'package:cpfhub/cpfhub.dart';

final client = CPFHubClient(
  apiKey: Platform.environment['CPFHUB_API_KEY']!,
  // timeout: Duration(seconds: 10), // opcional
);

Parâmetros do construtor

ParâmetroTipoPadrãoDescrição
apiKeyString-Sua API Key (obrigatório)
timeoutDuration10sTimeout da requisição
baseUrlStringhttps://api.cpfhub.ioURL base da API

Métodos

await client.lookup(String cpf)

Consulta um CPF e retorna os dados de identidade.

Dart
final result = await client.lookup('12345678909');

print(result.data.name);   // "João da Silva"
print(result.data.gender); // "M"

Retorno: CPFHubResult

Dart
class CPFHubResult {
  final bool success;
  final CPFData data;
}

class CPFData {
  final String cpf;
  final String name;
  final String nameUpper;
  final String gender;     // "M" | "F"
  final String birthDate;  // "DD/MM/AAAA"
  final int    day;
  final int    month;
  final int    year;
}

Tratamento de erros

Dart
import 'package:cpfhub/cpfhub.dart';

try {
  final result = await client.lookup('12345678909');
  print(result.data.name);
} on CPFHubException catch (e) {
  print(e.code);        // "CPF_NOT_FOUND"
  print(e.message);     // "CPF not found in our database"
  print(e.statusCode);  // 404
}

Códigos de erro

e.codee.statusCodeDescrição
CPF_NOT_FOUND404CPF não encontrado (sem consumo de crédito)
INVALID_CPF_FORMAT400Formato inválido
INVALID_CPF_DIGITS422Dígitos verificadores inválidos
MISSING_API_KEY401API Key ausente
INVALID_API_KEY401API Key inválida
RATE_LIMIT_EXCEEDED429Limite de taxa excedido
INSUFFICIENT_CREDITS403Sem créditos disponíveis

Exemplos de integração

Flutter - consulta em formulário

Dart
import 'package:flutter/material.dart';
import 'package:cpfhub/cpfhub.dart';

class CPFFormField extends StatefulWidget {
  const CPFFormField({super.key});

  @override
  State<CPFFormField> createState() => _CPFFormFieldState();
}

class _CPFFormFieldState extends State<CPFFormField> {
  final client = CPFHubClient(apiKey: const String.fromEnvironment('CPFHUB_API_KEY'));
  String? errorText;
  String? name;

  Future<void> _lookup(String cpf) async {
    setState(() { errorText = null; name = null; });
    try {
      final result = await client.lookup(cpf.replaceAll(RegExp(r'[^\d]'), ''));
      setState(() => name = result.data.name);
    } on CPFHubException catch (e) {
      setState(() => errorText = e.code == 'CPF_NOT_FOUND'
        ? 'CPF não encontrado'
        : 'Erro ao consultar CPF');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        TextFormField(
          decoration: InputDecoration(
            labelText: 'CPF',
            errorText: errorText,
          ),
          onEditingComplete: () => _lookup(/* controller.text */),
        ),
        if (name != null) Text('Nome: $name'),
      ],
    );
  }
}

Dart puro (servidor)

Dart
import 'dart:io';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart';
import 'package:cpfhub/cpfhub.dart';

final client = CPFHubClient(apiKey: Platform.environment['CPFHUB_API_KEY']!);

Response handler(Request request) async {
  final cpf = request.url.pathSegments.last;
  try {
    final result = await client.lookup(cpf);
    return Response.ok(jsonEncode(result.data.toJson()),
        headers: {'content-type': 'application/json'});
  } on CPFHubException catch (e) {
    return Response(e.statusCode, body: jsonEncode({'error': e.code}));
  }
}

void main() async {
  await serve(handler, InternetAddress.anyIPv4, 8080);
}

Repositório e suporte


Atualizado em 12 de maio de 2026