Para integrar a API de CPF da CPFHub.io em uma aplicação Go com Gin ou Echo, crie um cliente HTTP reutilizável com a chave x-api-key no header, encapsule a chamada em um middleware de validação e registre o handler no roteador do framework escolhido. Tanto Gin quanto Echo permitem essa integração em menos de 50 linhas de código, com suporte nativo a middleware, logging e tratamento de erros.
Introdução
Gin e Echo são os dois frameworks web mais populares em Go, oferecendo roteamento rápido, middleware flexível e excelente performance. Integrar a API de CPF em uma aplicação construída com esses frameworks envolve criar handlers, middleware de validação e um cliente HTTP reutilizável.
Comparação entre Gin e Echo
Ambos os frameworks são maduros e performáticos, com diferenças sutis na API.
| Característica | Gin | Echo |
|---|---|---|
| Performance | Excelente | Excelente |
| Popularidade (stars) | ~75k | ~28k |
| Middleware | Built-in + custom | Built-in + custom |
| Binding/Validação | JSON/XML/Form | JSON/XML/Form |
| Documentação | Extensa | Extensa |
| Context | *gin.Context | echo.Context |
| Resposta JSON | c.JSON(code, obj) | c.JSON(code, obj) |
Implementação com Gin
A integração com Gin utiliza handlers e middleware para validação de CPF.
package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"regexp"
"time"
"github.com/gin-gonic/gin"
)
type CPFHubClient struct {
httpClient *http.Client
apiKey string
baseURL string
}
type APIResponse struct {
Success bool `json:"success"`
Data struct {
CPF string `json:"cpf"`
Name string `json:"name"`
NameUpper string `json:"nameUpper"`
Gender string `json:"gender"`
BirthDate string `json:"birthDate"`
Day int `json:"day"`
Month int `json:"month"`
Year int `json:"year"`
} `json:"data"`
}
func NewCPFHubClient(apiKey string) *CPFHubClient {
return &CPFHubClient{
httpClient: &http.Client{Timeout: 10 * time.Second},
apiKey: apiKey,
baseURL: "https://api.cpfhub.io",
}
}
func (c *CPFHubClient) Consultar(cpf string) (*APIResponse, error) {
url := fmt.Sprintf("%s/cpf/%s", c.baseURL, cpf)
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, err
}
req.Header.Set("x-api-key", c.apiKey)
resp, err := c.httpClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var resultado APIResponse
if err := json.NewDecoder(resp.Body).Decode(&resultado); err != nil {
return nil, err
}
return &resultado, nil
}
// Middleware de validação de CPF para Gin
func ValidarCPFMiddleware() gin.HandlerFunc {
re := regexp.MustCompile(`\D`)
return func(c *gin.Context) {
cpf := re.ReplaceAllString(c.Param("cpf"), "")
if len(cpf) != 11 {
c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{
"erro": "CPF deve conter 11 digitos",
})
return
}
c.Set("cpf_limpo", cpf)
c.Next()
}
}
func setupGinRouter(client *CPFHubClient) *gin.Engine {
r := gin.Default()
api := r.Group("/api")
{
cpf := api.Group("/cpf")
cpf.Use(ValidarCPFMiddleware())
{
cpf.GET("/:cpf", func(c *gin.Context) {
cpfLimpo := c.GetString("cpf_limpo")
resultado, err := client.Consultar(cpfLimpo)
if err != nil {
c.JSON(http.StatusBadGateway, gin.H{
"erro": "Falha ao consultar API externa",
})
return
}
if !resultado.Success {
c.JSON(http.StatusNotFound, gin.H{
"erro": "CPF nao encontrado",
})
return
}
c.JSON(http.StatusOK, gin.H{
"sucesso": true,
"dados": resultado.Data,
})
})
}
}
r.GET("/health", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"status": "ok"})
})
return r
}
func main() {
apiKey := os.Getenv("CPFHUB_API_KEY")
client := NewCPFHubClient(apiKey)
r := setupGinRouter(client)
r.Run(":8080")
}
Implementação com Echo
A mesma funcionalidade implementada usando o framework Echo.
package main
import (
"net/http"
"os"
"regexp"
"github.com/labstack/echo/v4"
"github.com/labstack/echo/v4/middleware"
)
// ValidarCPFMiddleware para Echo
func ValidarCPFMiddlewareEcho(next echo.HandlerFunc) echo.HandlerFunc {
re := regexp.MustCompile(`\D`)
return func(c echo.Context) error {
cpf := re.ReplaceAllString(c.Param("cpf"), "")
if len(cpf) != 11 {
return c.JSON(http.StatusBadRequest, map[string]string{
"erro": "CPF deve conter 11 digitos",
})
}
c.Set("cpf_limpo", cpf)
return next(c)
}
}
func setupEchoRouter(client *CPFHubClient) *echo.Echo {
e := echo.New()
e.Use(middleware.Logger())
e.Use(middleware.Recover())
e.Use(middleware.CORS())
api := e.Group("/api")
cpfGroup := api.Group("/cpf")
cpfGroup.Use(ValidarCPFMiddlewareEcho)
cpfGroup.GET("/:cpf", func(c echo.Context) error {
cpfLimpo := c.Get("cpf_limpo").(string)
resultado, err := client.Consultar(cpfLimpo)
if err != nil {
return c.JSON(http.StatusBadGateway, map[string]string{
"erro": "Falha ao consultar API externa",
})
}
if !resultado.Success {
return c.JSON(http.StatusNotFound, map[string]string{
"erro": "CPF nao encontrado",
})
}
return c.JSON(http.StatusOK, map[string]interface{}{
"sucesso": true,
"dados": resultado.Data,
})
})
e.GET("/health", func(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
})
return e
}
func main() {
apiKey := os.Getenv("CPFHUB_API_KEY")
client := NewCPFHubClient(apiKey)
e := setupEchoRouter(client)
e.Logger.Fatal(e.Start(":8080"))
}
Middleware de rate limiting
Ambos os frameworks suportam middleware de rate limiting para proteger o serviço.
// Rate limiting com Gin (usando gin-contrib)
import "github.com/gin-contrib/limiter"
// Rate limiting com Echo (built-in)
e.Use(middleware.RateLimiter(
middleware.NewRateLimiterMemoryStore(20), // 20 req/s
))
| Configuração | Valor Recomendado | Framework |
|---|---|---|
| Rate limit global | 100 req/s | Gin e Echo |
| Rate limit por IP | 20 req/s | Gin e Echo |
| Timeout de requisição | 10 segundos | Ambos |
| Recovery middleware | Ativo | Ambos |
| CORS | Configurado | Ambos |
| Logger | Ativo | Ambos |
Testes de integração
Escreva testes para garantir que os endpoints funcionam corretamente.
package main
import (
"net/http"
"net/http/httptest"
"testing"
"github.com/stretchr/testify/assert"
)
func TestConsultarCPFGin(t *testing.T) {
// Mock da API externa
mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{
"success": true,
"data": {
"cpf": "12345678901",
"name": "Joao da Silva",
"nameUpper": "JOAO DA SILVA",
"gender": "M",
"birthDate": "1990-01-15",
"day": 15, "month": 1, "year": 1990
}
}`))
}))
defer mockServer.Close()
client := &CPFHubClient{
httpClient: mockServer.Client(),
apiKey: "test-key",
baseURL: mockServer.URL,
}
router := setupGinRouter(client)
w := httptest.NewRecorder()
req, _ := http.NewRequest("GET", "/api/cpf/12345678901", nil)
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusOK, w.Code)
assert.Contains(t, w.Body.String(), "Joao da Silva")
}
func TestCPFInvalidoGin(t *testing.T) {
client := NewCPFHubClient("test-key")
router := setupGinRouter(client)
w := httptest.NewRecorder()
req, _ := http.NewRequest("GET", "/api/cpf/123", nil)
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusBadRequest, w.Code)
}
Perguntas frequentes
Qual a diferença prática entre usar Gin e Echo para integrar a API de CPF?
Ambos funcionam de forma equivalente para integrar a CPFHub.io. A principal diferença está na API de contexto: Gin usa *gin.Context com métodos como c.GetString(), enquanto Echo usa echo.Context com c.Get(). O middleware de validação de CPF segue o mesmo padrão nos dois frameworks — a escolha é de preferência da equipe.
Como lidar com timeout na chamada à API de CPF em Go?
Configure http.Client{Timeout: 10 * time.Second} ao criar o cliente HTTP. Se o timeout for atingido, o erro context deadline exceeded é retornado e deve ser tratado no handler, retornando HTTP 504 ao cliente. A latência típica da CPFHub.io é de ~900ms, bem abaixo do limite de 10 segundos.
É necessário validar o formato do CPF antes de chamar a API?
Sim. Remova caracteres não numéricos com uma regex \D e confirme que o resultado tem exatamente 11 dígitos antes de fazer a chamada. Isso evita requisições desnecessárias e garante respostas de erro claras para o cliente da sua API.
Como reutilizar o cliente HTTP entre requisições em Go?
Instancie CPFHubClient uma única vez na inicialização da aplicação e injete-o nos handlers via closure ou dependência de roteador. O http.Client em Go é seguro para uso concorrente e reutilizar a mesma instância evita overhead de criação de conexão a cada requisição.
Conclusão
Integrar a API de CPF em aplicações Go com Gin ou Echo é direto e eficiente. Ambos os frameworks oferecem middleware flexível para validação, logging e rate limiting, tornando simples a criação de endpoints robustos para consulta de CPF. A escolha entre Gin e Echo depende da preferência da equipe, já que ambos entregam performance e funcionalidades equivalentes. A documentação oficial do Go detalha as melhores práticas para clientes HTTP reutilizáveis em produção.
Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a integrar a API de CPF na sua aplicação Go hoje mesmo.
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.
Sobre a redação
Redação CPFHub.io
Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.
