# Como consumir API de CPF em Terraform para validação em deploys

> Aprenda a consumir a API de consulta de CPF da CPFHub.io em Terraform usando data sources HTTP e provisioners para validação em pipelines de deploy.

**Publicado:** 06/03/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-terraform-para-validacao-em-deploys

---


Para consumir a API de CPF em Terraform, use o data source `http` com o endpoint `https://api.cpfhub.io/cpf/{CPF}` e o header `x-api-key`. Combine com `postcondition` para interromper o deploy caso a API não responda com sucesso — um padrão útil em pipelines de onboarding, compliance e smoke tests de integração.

O **Terraform** é a ferramenta de infraestrutura como código mais adotada no mercado. Em cenários onde a infraestrutura precisa provisionar serviços que dependem de validação de CPF — como ambientes de onboarding, compliance ou testes de integração — é possível incluir validações de API diretamente no pipeline de deploy. A documentação oficial do [Terraform](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec) descreve os provisioners `local-exec` como o mecanismo recomendado para executar scripts externos durante o provisionamento.

---

## 1. Cenários de uso

* **Smoke test em deploy** -- Verificar se a API da CPFHub.io está acessível antes de provisionar recursos que dependem dela.

* **Validação de configuração** -- Confirmar que a chave de API é válida durante o `terraform apply`.

* **Provisionamento de serviços** -- Configurar variáveis de ambiente com dados da API para containers e lambdas.

* **Ambientes de teste** -- Validar a integração em ambientes de staging antes de promover para produção.

---

## 2. Data source HTTP para teste de conectividade

O Terraform possui o data source `http` que permite fazer requisições GET durante o planejamento. Use-o para verificar se a API está acessível:

```hcl
variable "cpfhub_api_key" {
 description = "Chave de API da CPFHub.io"
 type = string
 sensitive = true
}

variable "cpf_teste" {
 description = "CPF para teste de conectividade"
 type = string
 default = "12345678900"
}

data "http" "cpfhub_health_check" {
 url = "https://api.cpfhub.io/cpf/${var.cpf_teste}"

 request_headers = {
 "x-api-key" = var.cpfhub_api_key
 "Accept" = "application/json"
 }

 request_timeout_ms = 5000
}

output "cpfhub_status" {
 value = data.http.cpfhub_health_check.status_code
}

output "cpfhub_response" {
 value = jsondecode(data.http.cpfhub_health_check.response_body)
 sensitive = true
}
```

---

## 3. Validação condicional com precondition

Use `precondition` para bloquear o deploy caso a API não responda com sucesso:

```hcl
data "http" "cpfhub_validation" {
 url = "https://api.cpfhub.io/cpf/${var.cpf_teste}"

 request_headers = {
 "x-api-key" = var.cpfhub_api_key
 "Accept" = "application/json"
 }

 request_timeout_ms = 5000

 lifecycle {
 postcondition {
 condition = self.status_code == 200
 error_message = "CPFHub API não está acessível. Deploy bloqueado."
 }
 }
}

resource "aws_ssm_parameter" "cpfhub_api_key" {
 depends_on = [data.http.cpfhub_validation]

 name = "/app/cpfhub/api-key"
 type = "SecureString"
 value = var.cpfhub_api_key
}
```

Se a API retornar um código diferente de 200, o `terraform apply` será interrompido com a mensagem de erro.

---

## 4. Provisionamento de variáveis para containers

Após validar a API, provisione as variáveis de ambiente para seus containers:

```hcl
resource "aws_ecs_task_definition" "app" {
 family = "app-service"
 container_definitions = jsonencode([
 {
 name = "app"
 image = "sua-imagem:latest"
 environment = [
 {
 name = "CPFHUB_BASE_URL"
 value = "https://api.cpfhub.io"
 }
 ]
 secrets = [
 {
 name = "CPFHUB_API_KEY"
 valueFrom = aws_ssm_parameter.cpfhub_api_key.arn
 }
 ]
 }
 ])
}
```

---

## 5. Script de validação com local-exec

Para validações mais elaboradas, use o provisioner `local-exec` com um script que consulta a API:

```hcl
resource "null_resource" "cpfhub_integration_test" {
 provisioner "local-exec" {
 command = <<-EOT
 response=$(curl -s -w "\n%%{http_code}" \
 --max-time 5 \
 -H "x-api-key: ${var.cpfhub_api_key}" \
 -H "Accept: application/json" \
 "https://api.cpfhub.io/cpf/${var.cpf_teste}")

 http_code=$(echo "$response" | tail -1)
 body=$(echo "$response" | head -1)

 if [ "$http_code" != "200" ]; then
 echo "ERRO: API CPFHub retornou HTTP $http_code"
 exit 1
 fi

 echo "API CPFHub validada com sucesso: $body"
 EOT
 }

 triggers = {
 always_run = timestamp()
 }
}
```

---

## 6. Exemplo de resposta da API

A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna um JSON com os dados cadastrais do titular em ~900ms:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "João da Silva",
 "nameUpper": "JOÃO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

---

## 7. Variáveis e backend seguro

Armazene a chave de API de forma segura, nunca em texto plano nos arquivos `.tf`:

```hcl
# terraform.tfvars (não comitar no repositório)
cpfhub_api_key = "SUA_CHAVE_DE_API"
```

Ou passe via variável de ambiente:

```bash
export TF_VAR_cpfhub_api_key="SUA_CHAVE_DE_API"
terraform apply
```

Adicione `terraform.tfvars` ao `.gitignore` para evitar exposição acidental.

---

## 8. Boas práticas

* **Timeout** -- Sempre configure `request_timeout_ms` no data source HTTP e `--max-time` no cURL para evitar que o pipeline trave indefinidamente.

* **Sensitive** -- Marque variáveis com `sensitive = true` para ocultar valores nos logs do Terraform.

* **Postcondition** -- Use postconditions para bloquear deploys quando dependências externas estão indisponíveis.

* **Idempotência** -- O data source HTTP é lido a cada `plan/apply`. Use `null_resource` com triggers para controlar quando a validação é executada.

* **Ambientes** -- Mantenha chaves de API diferentes para staging e produção usando workspaces ou backend separado.

---

## Perguntas frequentes

### Por que usar o data source HTTP do Terraform para validar a API de CPF?

O data source `http` executa durante o `terraform plan`, antes de qualquer recurso ser criado. Isso significa que a falha de conectividade com a API é detectada antes do deploy, evitando provisionamento parcial em ambientes que dependem da consulta de CPF para funcionar corretamente.

### Como armazenar a chave de API do CPFHub.io de forma segura no Terraform?

Nunca escreva a chave diretamente em arquivos `.tf`. Use variáveis do tipo `sensitive = true` e passe o valor via variável de ambiente (`TF_VAR_cpfhub_api_key`) ou via AWS Secrets Manager / HashiCorp Vault. Adicione `terraform.tfvars` ao `.gitignore` para evitar exposição acidental em repositórios.

### O `postcondition` bloqueia o deploy se a API estiver lenta?

O `postcondition` verifica apenas o código HTTP retornado — se for 200, o deploy prossegue. Para evitar falsos bloqueios por latência, configure `request_timeout_ms` com valor adequado (recomendado: 5000ms a 10000ms), já que a API tem latência média de ~900ms.

### Posso usar a validação de CPF no Terraform para ambientes de staging e produção ao mesmo tempo?

Sim. Use workspaces do Terraform ou backends separados para cada ambiente, com variáveis de API key distintas por workspace. Isso garante que um smoke test de staging não consuma cota do ambiente de produção e vice-versa.

### 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)
- [Como implementar validação de CPF em microsserviços com Docker e Kubernetes](https://cpfhub.io/blog/como-implementar-validacao-cpf-microsservicos-docker-kubernetes)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Como criar um SDK interno para padronizar consultas de CPF na empresa](https://cpfhub.io/blog/como-criar-sdk-interno-padronizar-consultas-cpf-empresa)

---

## Conclusão

Integrar a validação da API da [**CPFHub.io**](https://www.cpfhub.io/) diretamente no pipeline Terraform adiciona uma camada de segurança ao processo de deploy: se a dependência externa não estiver disponível ou mal configurada, o provisionamento para antes de criar recursos com comportamento incorreto. É uma prática especialmente útil em ambientes de onboarding e compliance, onde a consulta de CPF é crítica para o funcionamento do serviço.

Comece com o data source `http` para smoke tests simples e evolua para `null_resource` com `local-exec` quando precisar de validações mais elaboradas — como comparação de dados ou geração de evidências de auditoria.

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