Como integrar validação de CPF em AWS Lambda com Node.js

Integrar a validação de CPF em AWS Lambda com Node.js permite consultar o CPFHub.io de forma serverless, escalável e sem gerenciar servidores. Com resposta média de ~900ms e plano gratuito de 50 consultas mensais, a integração fica operacional em menos de 30 minutos — ideal para APIs de onboarding, webhooks de pagamento e eventos assíncronos.

Introdução

O AWS Lambda é um dos serviços serverless mais populares do mercado, permitindo executar código sem a necessidade de provisionar ou gerenciar servidores. Para aplicações que precisam validar CPFs sob demanda -- como APIs de onboarding, webhooks de pagamento ou processamento de eventos --, o Lambda é uma escolha natural, oferecendo escalabilidade automática e cobrança por execução.

A seguir, um guia completo em Node.js que integra a API da CPFHub.io ao AWS Lambda, cobrindo criação da função, configuração de variáveis de ambiente, API Gateway e boas práticas de segurança.

1. Pré-requisitos

• Conta AWS -- Com permissões para criar funções Lambda e configurar API Gateway.

• AWS CLI configurado -- Para deploy via linha de comando (opcional).

• Node.js 18 ou superior -- Runtime suportado pelo AWS Lambda.

• Conta na CPFHub.io -- Cadastre-se em CPFHub.io para obter sua API key gratuita.

2. Criando a função Lambda

Código da função

Crie um arquivo index.mjs com o seguinte conteúdo:

// index.mjs - AWS Lambda para validação de CPF via CPFHub.io

const API_BASE_URL = 'https://api.cpfhub.io/cpf';
const API_KEY = process.env.CPFHUB_API_KEY;

export const handler = async (event) => {
    const cpf = event.pathParameters?.cpf || event.queryStringParameters?.cpf;

    if (!cpf || !/^\d{11}$/.test(cpf)) {
    return {
    statusCode: 400,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
    error: 'CPF inválido. Informe 11 dígitos numéricos.',
    }),
    };
    }

    try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 30000);

    const response = await fetch(`${API_BASE_URL}/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json',
    },
    signal: controller.signal,
    });

    clearTimeout(timeoutId);

    const data = await response.json();

    if (response.ok && data.success) {
    return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
    success: true,
    data: {
    cpf: data.data.cpf,
    name: data.data.name,
    nameUpper: data.data.nameUpper,
    gender: data.data.gender,
    birthDate: data.data.birthDate,
    day: data.data.day,
    month: data.data.month,
    year: data.data.year,
    },
    }),
    };
    }

    return {
    statusCode: response.status,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
    error: 'Não foi possível validar o CPF.',
    details: data,
    }),
    };
    } catch (error) {
    console.error('Erro ao consultar CPFHub:', error.message);

    return {
    statusCode: 500,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
    error: 'Erro interno ao consultar a API.',
    }),
    };
    }
};

3. Configurando variáveis de ambiente

No console da AWS Lambda, adicione a variável de ambiente:

Via AWS CLI:

aws lambda update-function-configuration \
    --function-name validar-cpf \
    --environment "Variables={CPFHUB_API_KEY=SUA_CHAVE_DE_API}" \
    --timeout 30

Para maior segurança, armazene a chave no AWS Secrets Manager e recupere-a na função:

import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({ region: 'us-east-1' });

let cachedApiKey = null;

async function getApiKey() {
    if (cachedApiKey) return cachedApiKey;

    const command = new GetSecretValueCommand({ SecretId: 'cpfhub/api-key' });
    const response = await client.send(command);
    cachedApiKey = response.SecretString;
    return cachedApiKey;
}

4. Configurando API Gateway

Para expor a função Lambda como uma API HTTP, configure o API Gateway:

# Criar a API HTTP
aws apigatewayv2 create-api \
    --name "CPFValidation" \
    --protocol-type HTTP \
    --target "arn:aws:lambda:us-east-1:123456789:function:validar-cpf"

A rota recomendada é GET /cpf/{cpf}, espelhando a estrutura da API da CPFHub.io.

5. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com os dados do titular do CPF consultado:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success -- Indica se a consulta foi bem-sucedida.
• name / nameUpper -- Nome completo do titular.
• gender -- Gênero (M ou F).
• birthDate -- Data de nascimento completa.
• day, month, year -- Componentes da data separados.

6. Deploy com SAM (Serverless Application Model)

Para projetos mais estruturados, utilize o AWS SAM:

# template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
    Function:
    Timeout: 30
    Runtime: nodejs18.x

Resources:
    ValidarCpfFunction:
    Type: AWS::Serverless::Function
    Properties:
    Handler: index.handler
    CodeUri: ./src
    Environment:
    Variables:
    CPFHUB_API_KEY: !Ref CpfHubApiKey
    Events:
    ValidarCpf:
    Type: HttpApi
    Properties:
    Path: /cpf/{cpf}
    Method: GET

Parameters:
    CpfHubApiKey:
    Type: String
    NoEcho: true
    Description: Chave de API da CPFHub.io

Deploy:

sam build && sam deploy --guided

7. Testando localmente

Teste a função localmente com o SAM CLI:

# Criar evento de teste
echo '{"pathParameters":{"cpf":"12345678900"}}' > event.json

# Executar localmente
sam local invoke ValidarCpfFunction --event event.json

Ou teste via cURL após o deploy:

curl -X GET "https://seu-api-id.execute-api.us-east-1.amazonaws.com/cpf/12345678900" \
    --max-time 30

8. Boas práticas para Lambda

• Configure timeout adequado -- Defina o timeout da Lambda para pelo menos 30 segundos, considerando o tempo de resposta da API (~900ms) mais margem para cold starts.

• Reutilize conexões -- O Node.js no Lambda mantém conexões HTTP entre invocações quentes. Aproveite isso para melhor performance.

• Implemente cache -- Utilize DynamoDB ou ElastiCache para armazenar resultados de consultas recentes e reduzir chamadas à API.

• Monitore com CloudWatch -- Configure alarmes para erros e latência elevada.

• Gerencie o volume de consultas -- O plano gratuito oferece 50 consultas/mês sem cartão de crédito; para volumes maiores, o plano Pro (R$149/mês) inclui 1.000 consultas mensais. A API nunca bloqueia — consultas além do limite são cobradas a R$0,15 cada. Consulte a documentação do AWS Lambda para estratégias de throttling no lado do gateway.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

O AWS Lambda combinado com Node.js oferece uma plataforma serverless ideal para validação de CPF sob demanda. A integração com a API da CPFHub.io entrega escalabilidade automática, cobrança por execução e resposta média de ~900ms — sem a complexidade de gerenciar infraestrutura.

A CPFHub.io oferece conformidade LGPD, tempo de resposta de aproximadamente 900ms e 99,9% de uptime, garantindo confiabilidade para funções serverless em produção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.