Tutorial Completo: Integrando API CPF em Node.js e Express

Introdução

Node.js e Express são uma das combinações mais populares para desenvolvimento de APIs e aplicações web. Neste tutorial completo, você aprenderá a integrar a API CPF Nacional em uma aplicação Node.js/Express, incluindo tratamento de erros, cache e otimizações de performance.

Pré-requisitos

• Node.js instalado (versão 14 ou superior)
• npm ou yarn
• Conta na API CPF Nacional (gratuita)
• Conhecimento básico de JavaScript e Express

Configuração Inicial

1. Criar o Projeto

mkdir api-cpf-nodejs
cd api-cpf-nodejs
npm init -y
npm install express axios dotenv

2. Estrutura de Arquivos

api-cpf-nodejs/
├── .env
├── index.js
├── routes/
│   └── cpf.js
├── services/
│   └── cpfService.js
└── middleware/
    └── cache.js

Implementação Completa

1. Arquivo .env

PORT=3000
CPF_API_KEY=sua-chave-api-aqui
CPF_API_URL=https://api.cpf-brasil.org/api.php

2. Serviço de CPF (services/cpfService.js)

const axios = require('axios');

class CPFService {
    constructor() {
        this.apiKey = process.env.CPF_API_KEY;
        this.apiUrl = process.env.CPF_API_URL;
    }
    
    async consultarCPF(cpf) {
        try {
            // Limpar CPF (remover caracteres não numéricos)
            const cpfLimpo = cpf.replace(/[^0-9]/g, '');
            
            // Validar formato
            if (cpfLimpo.length !== 11) {
                throw new Error('CPF deve conter 11 dígitos');
            }
            
            // Fazer requisição à API
            const response = await axios.get(`${this.apiUrl}?cpf=${cpfLimpo}`, {
                headers: {
                    'X-API-Key': this.apiKey
                },
                timeout: 5000 // 5 segundos
            });
            
            if (response.data.success) {
                return {
                    success: true,
                    data: response.data.data
                };
            } else {
                return {
                    success: false,
                    error: response.data.error || 'CPF inválido'
                };
            }
        } catch (error) {
            // Tratamento de erros
            if (error.response) {
                return {
                    success: false,
                    error: 'Erro na API: ' + error.response.status
                };
            } else if (error.request) {
                return {
                    success: false,
                    error: 'Erro de conexão com a API'
                };
            } else {
                return {
                    success: false,
                    error: error.message
                };
            }
        }
    }
}

module.exports = new CPFService();

3. Middleware de Cache (middleware/cache.js)

const NodeCache = require('node-cache');

const cache = new NodeCache({ stdTTL: 3600 }); // Cache de 1 hora

function cacheMiddleware(req, res, next) {
    const cpf = req.params.cpf || req.query.cpf;
    const cacheKey = `cpf_${cpf}`;
    
    // Verificar cache
    const cached = cache.get(cacheKey);
    if (cached) {
        return res.json({
            success: true,
            data: cached,
            cached: true
        });
    }
    
    // Adicionar função para salvar no cache
    res.cacheData = (data) => {
        cache.set(cacheKey, data);
    };
    
    next();
}

module.exports = cacheMiddleware;

4. Rotas (routes/cpf.js)

const express = require('express');
const router = express.Router();
const cpfService = require('../services/cpfService');
const cacheMiddleware = require('../middleware/cache');

// Rota para consultar CPF
router.get('/consultar/:cpf', cacheMiddleware, async (req, res) => {
    try {
        const { cpf } = req.params;
        
        const resultado = await cpfService.consultarCPF(cpf);
        
        if (resultado.success) {
            // Salvar no cache
            if (res.cacheData) {
                res.cacheData(resultado.data);
            }
            
            res.json({
                success: true,
                data: resultado.data
            });
        } else {
            res.status(400).json({
                success: false,
                error: resultado.error
            });
        }
    } catch (error) {
        res.status(500).json({
            success: false,
            error: 'Erro interno do servidor'
        });
    }
});

// Rota para validar CPF
router.post('/validar', async (req, res) => {
    try {
        const { cpf } = req.body;
        
        if (!cpf) {
            return res.status(400).json({
                success: false,
                error: 'CPF não fornecido'
            });
        }
        
        const resultado = await cpfService.consultarCPF(cpf);
        
        res.json({
            success: resultado.success,
            valido: resultado.success
        });
    } catch (error) {
        res.status(500).json({
            success: false,
            error: 'Erro interno do servidor'
        });
    }
});

module.exports = router;

5. Arquivo Principal (index.js)

require('dotenv').config();
const express = require('express');
const cpfRoutes = require('./routes/cpf');

const app = express();
const PORT = process.env.PORT || 3000;

// Middlewares
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Rotas
app.use('/api/cpf', cpfRoutes);

// Rota de health check
app.get('/health', (req, res) => {
    res.json({ status: 'ok' });
});

// Iniciar servidor
app.listen(PORT, () => {
    console.log(`Servidor rodando na porta ${PORT}`);
});

Otimizações de Performance

1. Cache de Resultados

Use cache para evitar consultas repetidas ao mesmo CPF:

npm install node-cache

2. Rate Limiting

Implemente rate limiting para proteger sua API:

npm install express-rate-limit

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutos
    max: 100 // máximo 100 requisições por IP
});

app.use('/api/cpf', limiter);

Tratamento de Erros

Sempre trate erros adequadamente:

• Timeouts de conexão
• Erros de rede
• Respostas inválidas da API
• Rate limiting

Testes

// Teste básico
curl http://localhost:3000/api/cpf/consultar/12345678901

// Teste de validação
curl -X POST http://localhost:3000/api/cpf/validar \
  -H "Content-Type: application/json" \
  -d '{"cpf":"12345678901"}'

Conclusão

Com esta implementação completa, você tem uma base sólida para integrar a API CPF Nacional em suas aplicações Node.js/Express. Lembre-se de sempre tratar erros, implementar cache e seguir as melhores práticas de segurança.