# Como integrar validação de CPF em AWS Lambda com Node.js e API Gateway

> Aprenda a criar uma função AWS Lambda com Node.js que consome a API de CPF, exposta via API Gateway com autenticação e tratamento de erros.

**Publicado:** 17/09/2026
**Autor:** Redação CPFHub.io
**URL:** https://www.cpfhub.io/blog/como-integrar-validacao-cpf-aws-lambda-nodejs-api-gateway

---


Para integrar validação de CPF em AWS Lambda com Node.js, crie uma função que recebe o CPF via path parameter, consulta a API da CPFHub.io com o header `x-api-key` e retorna os dados do titular. Combinada ao API Gateway, essa arquitetura serverless escala automaticamente de zero a milhares de requisições sem custo fixo de infraestrutura. A chave de API deve ser armazenada no AWS Secrets Manager e cacheada em memória para evitar chamadas desnecessárias entre invocações. A documentação oficial da [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) detalha as opções de configuração de runtime e permissões IAM necessárias.

---

## Arquitetura da solução

A arquitetura serverless para validação de CPF segue o padrão:

1. O cliente envia uma requisição HTTP para o API Gateway.
2. O API Gateway roteia a requisição para a função Lambda.
3. A Lambda recupera a chave de API do Secrets Manager.
4. A Lambda consulta a API da CPFHub.io.
5. A resposta e retornada ao cliente via API Gateway.

Essa arquitetura escala automaticamente de zero a milhares de requisições simultaneas, sem necessidade de gerenciar infraestrutura.

---

## Implementação da função Lambda

Veja a implementação completa da função Lambda em Node.js 20:

```javascript
// handler.js
const { SecretsManagerClient, GetSecretValueCommand } = require("@aws-sdk/client-secrets-manager");

const secretsClient = new SecretsManagerClient({ region: "sa-east-1" });
let cachedApiKey = null;

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

 const command = new GetSecretValueCommand({
 SecretId: "cpfhub/api-key",
 });

 const response = await secretsClient.send(command);
 cachedApiKey = response.SecretString;
 return cachedApiKey;
}

async function consultarCPF(cpfNumero, apiKey) {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 10000);

 try {
 const response = await fetch(
 `https://api.cpfhub.io/cpf/${cpfNumero}`,
 {
 method: "GET",
 headers: {
 "x-api-key": apiKey,
 "Accept": "application/json",
 },
 signal: controller.signal,
 }
 );

 clearTimeout(timeoutId);

 if (!response.ok) {
 throw new Error(`API retornou status ${response.status}`);
 }

 return await response.json();
 } catch (error) {
 clearTimeout(timeoutId);

 if (error.name === "AbortError") {
 throw new Error("Timeout na consulta de CPF");
 }
 throw error;
 }
}

function criarResposta(statusCode, body) {
 return {
 statusCode,
 headers: {
 "Content-Type": "application/json",
 "Access-Control-Allow-Origin": "*",
 "Access-Control-Allow-Methods": "GET,OPTIONS",
 },
 body: JSON.stringify(body),
 };
}

exports.handler = async (event) => {
 // Tratar preflight CORS
 if (event.httpMethod === "OPTIONS") {
 return criarResposta(200, {});
 }

 const cpf = event.pathParameters?.cpf;

 if (!cpf) {
 return criarResposta(400, { erro: "CPF e obrigatorio" });
 }

 const cpfLimpo = cpf.replace(/\D/g, "");

 if (cpfLimpo.length !== 11) {
 return criarResposta(400, { erro: "CPF deve conter 11 digitos" });
 }

 // Rejeitar CPFs com todos os digitos iguais
 if (/^(\d)\1+$/.test(cpfLimpo)) {
 return criarResposta(400, { erro: "CPF invalido" });
 }

 try {
 const apiKey = await getApiKey();
 const resultado = await consultarCPF(cpfLimpo, apiKey);

 if (!resultado.success || !resultado.data) {
 return criarResposta(404, { erro: "CPF nao encontrado" });
 }

 return criarResposta(200, {
 valido: true,
 dados: {
 nome: resultado.data.name,
 cpf: resultado.data.cpf,
 genero: resultado.data.gender,
 dataNascimento: resultado.data.birthDate,
 },
 });
 } catch (error) {
 console.error("Erro na consulta:", error.message);
 return criarResposta(500, {
 erro: "Falha na consulta de CPF",
 detalhe: error.message,
 });
 }
};
```

O segredo da chave de API e recuperado do AWS Secrets Manager e cacheado em memoria entre invocacoes da Lambda -- uma otimizacao que evita chamadas desnecessarias ao Secrets Manager em ambientes com alta concorrencia.

---

## Template AWS SAM para deploy

O AWS SAM (Serverless Application Model) simplifica o deploy da infraestrutura. Crie o arquivo `template.yaml`:

```yaml
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: API de validacao de CPF com CPFHub.io

Globals:
 Function:
 Timeout: 15
 Runtime: nodejs20.x
 MemorySize: 256
 Environment:
 Variables:
 NODE_ENV: production

Resources:
 ValidarCPFFunction:
 Type: AWS::Serverless::Function
 Properties:
 Handler: handler.handler
 CodeUri: ./src
 Description: Consulta e valida CPF via API CPFHub.io
 Policies:
 - Statement:
 - Effect: Allow
 Action: secretsmanager:GetSecretValue
 Resource: !Sub "arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:cpfhub/api-key-*"
 Events:
 ValidarCPF:
 Type: Api
 Properties:
 Path: /cpf/{cpf}
 Method: GET
 ValidarCPFOptions:
 Type: Api
 Properties:
 Path: /cpf/{cpf}
 Method: OPTIONS

Outputs:
 ApiUrl:
 Description: URL da API de validacao de CPF
 Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/cpf/"
```

Deploy com:

```bash
sam build && sam deploy --guided
```

---

## Configuração do API Gateway

O API Gateway oferece recursos adicionais de seguranca e controle:

### Rate limiting

Configure um Usage Plan no API Gateway para limitar requisições:

```yaml
# Adicionar ao template.yaml
ApiUsagePlan:
 Type: AWS::ApiGateway::UsagePlan
 Properties:
 UsagePlanName: cpf-validation-plan
 Throttle:
 BurstLimit: 10
 RateLimit: 5
 Quota:
 Limit: 1000
 Period: MONTH
```

### Validação de request

O API Gateway pode validar o formato do CPF antes de invocar a Lambda, economizando execucoes desnecessarias:

```yaml
# Model de validacao no API Gateway
{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
 "cpf": {
 "type": "string",
 "pattern": "^\\d{11}$"
 }
 },
 "required": ["cpf"]
}
```

---

## Monitoramento com CloudWatch

A Lambda envia metricas automaticamente para o CloudWatch. Configure alarmes para monitorar a integração:

```javascript
// Adicionar metricas customizadas no handler
const { CloudWatchClient, PutMetricDataCommand } = require("@aws-sdk/client-cloudwatch");

const cwClient = new CloudWatchClient({ region: "sa-east-1" });

async function registrarMetrica(nome, valor, unidade = "Count") {
 await cwClient.send(new PutMetricDataCommand({
 Namespace: "CPFValidation",
 MetricData: [{
 MetricName: nome,
 Value: valor,
 Unit: unidade,
 Timestamp: new Date(),
 }],
 }));
}

// No handler, apos a consulta:
await registrarMetrica("ConsultasSucesso", 1);
// Ou em caso de falha:
await registrarMetrica("ConsultasFalha", 1);
```

---

## Otimizacao de cold start

O cold start e o principal desafio de funções Lambda. Para minimiza-lo na integração com a API de CPF:

* **Provisioned Concurrency** -- Mantem instancias quentes para rotas críticas. Configure pelo menos 1 instancia para evitar cold starts em horarios de pico.
* **Minimizar dependências** -- Use o fetch nativo do Node.js 20 em vez de bibliotecas como Axios. Menos código significa menos tempo de inicializacao.
* **Cache do Secrets Manager** -- O cache da chave de API em variavel global (como implementado acima) evita chamadas extras ao Secrets Manager em invocacoes quentes.
* **Tamanho de memoria** -- Aumentar a memoria da Lambda também aumenta a CPU alocada, acelerando a inicializacao.

| Memoria (MB) | Cold start medio | Custo por 1M invocacoes |
|---------------|------------------|-------------------------|
| 128 | ~800ms | ~$0.21 |
| 256 | ~450ms | ~$0.42 |
| 512 | ~250ms | ~$0.84 |

---

## Testes locais com SAM CLI

O SAM CLI permite testar a Lambda localmente antes do deploy:

```bash
# Criar evento de teste
echo '{"httpMethod":"GET","pathParameters":{"cpf":"12345678901"}}' > event.json

# Executar localmente
sam local invoke ValidarCPFFunction -e event.json

# Subir API local
sam local start-api --port 3000
```

Com a API local rodando, teste com curl:

```bash
curl http://localhost:3000/cpf/12345678901
```

---

## Custos estimados

A combinação Lambda + API Gateway e extremamente econômica para volumes moderados:

| Componente | Custo | 1.000 consultas/mes |
|-----------------|--------------------------------|----------------------|
| Lambda | $0.20 por 1M requisições | ~$0.00 |
| API Gateway | $3.50 por 1M requisições | ~$0.004 |
| Secrets Manager | $0.40/segredo/mes | $0.40 |
| CPFHub.io Pro | R$149/mes (1.000 consultas) | R$149.00 |

O custo de infraestrutura AWS para 1.000 consultas mensais e praticamente zero, tornando o plano Pro da [**CPFHub.io**](https://www.cpfhub.io/)

---

## Perguntas frequentes

### O que é necessário para integrar validação de CPF em AWS Lambda?

A integração exige uma função Lambda em Node.js configurada para receber o CPF via path parameter, um API Gateway expondo a rota HTTP e a chave de API da CPFHub.io armazenada no Secrets Manager. A Lambda faz uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key` e retorna nome, gênero e data de nascimento do titular.

### Qual é a latência esperada da API CPFHub.io dentro de uma Lambda?

A API CPFHub.io tem latência média de ~900ms. Somado ao tempo de execução da Lambda (especialmente em cold starts com 128MB de memória, que podem chegar a ~800ms), o tempo total de resposta gira em torno de 1,5 a 2 segundos. Configure o timeout da Lambda em pelo menos 15 segundos para absorver variações.

### A API CPFHub.io bloqueia quando o limite de consultas é atingido?

Não. Quando o limite mensal do plano é ultrapassado, a API não bloqueia nem retorna erro 429 — ela continua respondendo e cobra R$0,15 por consulta adicional. O plano gratuito inclui 50 consultas/mês e o plano Pro oferece 1.000 consultas por R$149/mês.

### Como armazenar a chave de API da CPFHub.io de forma segura na Lambda?

Use o AWS Secrets Manager para armazenar a chave e recuperá-la na inicialização da função, cacheando-a em uma variável global. Essa abordagem evita chamadas repetidas ao Secrets Manager em invocações quentes e mantém a chave fora de variáveis de ambiente em texto plano, reduzindo o risco de exposição em logs.

### 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)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)
- [Como implementar validação de CPF em microsserviços com Docker e Kubernetes](https://cpfhub.io/blog/como-implementar-validacao-cpf-microsservicos-docker-kubernetes)

---

## Conclusão

AWS Lambda com API Gateway e a combinação classica para APIs serverless, e a integração com a API de CPF da [**CPFHub.io**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)