# Como Criar um Microsserviço de Validação de CPF em Go

> Aprenda a criar um microsserviço de validação de CPF em Go, com endpoints REST, validação algorítmica, consulta via API e containerização.

**Publicado:** 26/08/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/microsservico-validacao-cpf-go

---


Para criar um microsserviço de validação de CPF em Go, estruture o projeto com separação de responsabilidades — handler HTTP, serviço de negócio, cliente da API externa e validador algorítmico — containerize com Docker em imagem multi-stage e exponha um endpoint REST que valida o CPF localmente antes de consultar a CPFHub.io para confirmar os dados do titular. A linguagem Go garante baixo consumo de memória e alta performance em I/O, tornando esse microsserviço capaz de atender milhares de requisições por segundo com recursos mínimos.

## Introdução

Go é uma linguagem ideal para microsserviços: compilação estática, baixo consumo de memória, excelente performance em I/O e concorrência nativa com goroutines. Um microsserviço de validação de CPF em Go pode atender milhares de requisições por segundo com recursos mínimos, servindo como ponto centralizado de validação para todas as aplicações da organização.

## Estrutura do projeto

A estrutura segue o padrão de projetos Go com separação clara de responsabilidades.

```go
// Estrutura de diretórios
// cpf-service/
// cmd/
// server/
// main.go
// internal/
// handler/
// cpf_handler.go
// service/
// cpf_service.go
// client/
// cpfhub_client.go
// validator/
// cpf_validator.go
// model/
// cpf.go
// go.mod
// go.sum
// Dockerfile
```

| Diretório | Responsabilidade |
|---|---|
| `cmd/server` | Ponto de entrada da aplicação |
| `internal/handler` | Handlers HTTP (controllers) |
| `internal/service` | Lógica de negócio |
| `internal/client` | Cliente HTTP para a API externa |
| `internal/validator` | Validação algorítmica de CPF |
| `internal/model` | Modelos de dados |

---

## Modelos e validador de CPF

Defina os modelos de dados e a validação algorítmica do CPF.

```go
// internal/model/cpf.go
package model

type ConsultaCPFRequest struct {
 CPF string `json:"cpf"`
}

type ConsultaCPFResponse struct {
 Sucesso bool `json:"sucesso"`
 Fonte string `json:"fonte"`
 Dados *DadosCPF `json:"dados,omitempty"`
 Erro string `json:"erro,omitempty"`
}

type DadosCPF struct {
 CPF string `json:"cpf"`
 Nome string `json:"name"`
 NomeUpper string `json:"nameUpper"`
 Genero string `json:"gender"`
 DataNascimento string `json:"birthDate"`
 Dia int `json:"day"`
 Mes int `json:"month"`
 Ano int `json:"year"`
}

type APIResponse struct {
 Success bool `json:"success"`
 Data *DadosCPF `json:"data,omitempty"`
}

// internal/validator/cpf_validator.go
package validator

import (
 "regexp"
 "strconv"
)

var apenasDigitos = regexp.MustCompile(`\D`)

func LimparCPF(cpf string) string {
 return apenasDigitos.ReplaceAllString(cpf, "")
}

func ValidarCPF(cpf string) bool {
 cpfLimpo := LimparCPF(cpf)

 if len(cpfLimpo) != 11 {
 return false
 }

 // Verificar se todos os dígitos são iguais
 todosIguais := true
 for i := 1; i < 11; i++ {
 if cpfLimpo[i] != cpfLimpo[0] {
 todosIguais = false
 break
 }
 }
 if todosIguais {
 return false
 }

 // Validar primeiro dígito verificador
 soma := 0
 for i := 0; i < 9; i++ {
 d, _ := strconv.Atoi(string(cpfLimpo[i]))
 soma += d * (10 - i)
 }
 resto := (soma * 10) % 11
 if resto == 10 {
 resto = 0
 }
 d9, _ := strconv.Atoi(string(cpfLimpo[9]))
 if resto != d9 {
 return false
 }

 // Validar segundo dígito verificador
 soma = 0
 for i := 0; i < 10; i++ {
 d, _ := strconv.Atoi(string(cpfLimpo[i]))
 soma += d * (11 - i)
 }
 resto = (soma * 10) % 11
 if resto == 10 {
 resto = 0
 }
 d10, _ := strconv.Atoi(string(cpfLimpo[10]))
 return resto == d10
}
```

---

## Cliente HTTP para a API do CPFHub

O cliente encapsula as chamadas à API externa com timeout e tratamento de erros.

```go
// internal/client/cpfhub_client.go
package client

import (
 "encoding/json"
 "fmt"
 "net/http"
 "time"

 "cpf-service/internal/model"
)

type CPFHubClient struct {
 httpClient *http.Client
 baseURL string
 apiKey string
}

func NewCPFHubClient(apiKey string) *CPFHubClient {
 return &CPFHubClient{
 httpClient: &http.Client{
 Timeout: 10 * time.Second,
 },
 baseURL: "https://api.cpfhub.io",
 apiKey: apiKey,
 }
}

func (c *CPFHubClient) ConsultarCPF(cpf string) (*model.APIResponse, error) {
 url := fmt.Sprintf("%s/cpf/%s", c.baseURL, cpf)

 req, err := http.NewRequest("GET", url, nil)
 if err != nil {
 return nil, fmt.Errorf("erro ao criar requisicao: %w", err)
 }

 req.Header.Set("x-api-key", c.apiKey)
 req.Header.Set("Content-Type", "application/json")

 resp, err := c.httpClient.Do(req)
 if err != nil {
 return nil, fmt.Errorf("erro na requisicao: %w", err)
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
 return nil, fmt.Errorf("API retornou status %d", resp.StatusCode)
 }

 var resultado model.APIResponse
 if err := json.NewDecoder(resp.Body).Decode(&resultado); err != nil {
 return nil, fmt.Errorf("erro ao decodificar resposta: %w", err)
 }

 return &resultado, nil
}
```

---

## Handler HTTP e server

O handler processa as requisições HTTP e o server inicializa a aplicação.

```go
// internal/handler/cpf_handler.go
package handler

import (
 "encoding/json"
 "net/http"

 "cpf-service/internal/client"
 "cpf-service/internal/model"
 "cpf-service/internal/validator"
)

type CPFHandler struct {
 apiClient *client.CPFHubClient
}

func NewCPFHandler(apiClient *client.CPFHubClient) *CPFHandler {
 return &CPFHandler{apiClient: apiClient}
}

func (h *CPFHandler) Consultar(w http.ResponseWriter, r *http.Request) {
 cpf := r.PathValue("cpf")
 cpfLimpo := validator.LimparCPF(cpf)

 w.Header().Set("Content-Type", "application/json")

 if !validator.ValidarCPF(cpfLimpo) {
 w.WriteHeader(http.StatusBadRequest)
 json.NewEncoder(w).Encode(model.ConsultaCPFResponse{
 Sucesso: false,
 Erro: "CPF invalido",
 })
 return
 }

 resultado, err := h.apiClient.ConsultarCPF(cpfLimpo)
 if err != nil {
 w.WriteHeader(http.StatusBadGateway)
 json.NewEncoder(w).Encode(model.ConsultaCPFResponse{
 Sucesso: false,
 Erro: "Erro ao consultar API externa",
 })
 return
 }

 if !resultado.Success {
 w.WriteHeader(http.StatusNotFound)
 json.NewEncoder(w).Encode(model.ConsultaCPFResponse{
 Sucesso: false,
 Fonte: "api",
 Erro: "CPF nao encontrado",
 })
 return
 }

 json.NewEncoder(w).Encode(model.ConsultaCPFResponse{
 Sucesso: true,
 Fonte: "api",
 Dados: resultado.Data,
 })
}

// cmd/server/main.go
package main

import (
 "fmt"
 "log"
 "net/http"
 "os"

 "cpf-service/internal/client"
 "cpf-service/internal/handler"
)

func main() {
 apiKey := os.Getenv("CPFHUB_API_KEY")
 if apiKey == "" {
 log.Fatal("CPFHUB_API_KEY nao definida")
 }

 apiClient := client.NewCPFHubClient(apiKey)
 cpfHandler := handler.NewCPFHandler(apiClient)

 mux := http.NewServeMux()
 mux.HandleFunc("GET /api/cpf/{cpf}", cpfHandler.Consultar)
 mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
 w.WriteHeader(http.StatusOK)
 fmt.Fprint(w, `{"status":"ok"}`)
 })

 port := os.Getenv("PORT")
 if port == "" {
 port = "8080"
 }

 log.Printf("Servidor iniciado na porta %s", port)
 log.Fatal(http.ListenAndServe(":"+port, mux))
}
```

---

## Dockerfile para containerização

A imagem multi-stage mantém o container final leve e seguro.

```dockerfile
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /cpf-service ./cmd/server

FROM alpine:3.19
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /cpf-service .
EXPOSE 8080
CMD ["./cpf-service"]
```

| Estágio | Imagem Base | Tamanho | Propósito |
|---|---|---|---|
| Builder | golang:1.22-alpine | ~300MB | Compilação do binário |
| Runtime | alpine:3.19 | ~15MB | Execução do serviço |

---

## 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 em menos de 200ms, 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

- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos)
- [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei)

---

## Conclusão

Um microsserviço de validação de CPF em Go combina a performance excepcional da linguagem com uma arquitetura limpa e containerizável. Com validação algorítmica local, consulta via API externa e endpoints REST, o serviço pode atender milhares de requisições por segundo com consumo mínimo de recursos. A containerização com Docker facilita o deploy em qualquer ambiente de orquestração.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a construir seu microsserviço de validação de CPF com dados reais hoje mesmo.