# Como integrar validação de CPF em AWS Lambda com Node.js > Aprenda a integrar validação de CPF em AWS Lambda usando Node.js. Exemplos com API Gateway, variáveis de ambiente e boas práticas serverless. **Publicado:** 03/09/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-aws-lambda-com-nodejs --- 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**](https://www.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**](https://www.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: ```javascript // 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: | Chave | Valor | | --- | --- | | CPFHUB_API_KEY | SUA_CHAVE_DE_API | Via AWS CLI: ```bash 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: ```javascript 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: ```bash # 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**](https://www.cpfhub.io/) retorna um JSON estruturado com os dados do titular do CPF consultado: ```json { "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: ```yaml # 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: ```bash sam build && sam deploy --guided ``` --- ## 7. Testando localmente Teste a função localmente com o SAM CLI: ```bash # 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: ```bash 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](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) 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](https://www.gov.br/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. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## 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**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.