Go é uma linguagem ideal para construir serviços de alta performance que consomem APIs externas. Com sua biblioteca padrão net/http e a biblioteca resty, é possível integrar a API de consulta de CPF da CPFHub.io com tratamento de erros robusto, timeouts configuráveis e paralelismo nativo via goroutines. O endpoint GET https://api.cpfhub.io/cpf/{CPF} retorna nome, data de nascimento e gênero do titular em cerca de 900ms, autenticado via header x-api-key.
Usando net/http (biblioteca padrão)
package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type CPFResponse struct {
Success bool `json:"success"`
Data CPFData `json:"data"`
}
type CPFData 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"`
}
func consultarCPF(cpf string) (*CPFResponse, error) {
client := &http.Client{Timeout: 10 * time.Second}
url := fmt.Sprintf("https://api.cpfhub.io/cpf/%s", cpf)
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, err
}
req.Header.Set("x-api-key", os.Getenv("CPFHUB_API_KEY"))
req.Header.Set("Accept", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
}
var resultado CPFResponse
if err := json.NewDecoder(resp.Body).Decode(&resultado); err != nil {
return nil, err
}
return &resultado, nil
}
func main() {
resultado, err := consultarCPF("12345678900")
if err != nil {
fmt.Printf("Erro: %v\n", err)
return
}
if resultado.Success {
fmt.Printf("Nome: %s\n", resultado.Data.Name)
fmt.Printf("Nascimento: %s\n", resultado.Data.BirthDate)
} else {
fmt.Println("CPF nao encontrado")
}
}
Usando resty
Instalação
go get github.com/go-resty/resty/v2
Consulta com resty
package main
import (
"fmt"
"os"
"time"
"github.com/go-resty/resty/v2"
)
func main() {
client := resty.New().
SetBaseURL("https://api.cpfhub.io").
SetTimeout(10 * time.Second).
SetHeader("x-api-key", os.Getenv("CPFHUB_API_KEY")).
SetHeader("Accept", "application/json").
SetRetryCount(3).
SetRetryWaitTime(1 * time.Second).
SetRetryMaxWaitTime(8 * time.Second).
AddRetryCondition(func(r *resty.Response, err error) bool {
if err != nil {
return true
}
return r.StatusCode() >= 500
})
var resultado CPFResponse
resp, err := client.R().
SetResult(&resultado).
Get("/cpf/12345678900")
if err != nil {
fmt.Printf("Erro: %v\n", err)
return
}
if resp.IsError() {
fmt.Printf("HTTP %d\n", resp.StatusCode())
return
}
if resultado.Success {
fmt.Printf("Nome: %s\n", resultado.Data.Name)
fmt.Printf("Nascimento: %s\n", resultado.Data.BirthDate)
}
}
Consultas em paralelo com goroutines
func consultarLote(cpfs []string) []CPFResponse {
resultados := make([]CPFResponse, len(cpfs))
ch := make(chan struct{ idx int; resp CPFResponse }, len(cpfs))
for i, cpf := range cpfs {
go func(idx int, cpf string) {
resp, err := consultarCPF(cpf)
if err != nil {
ch <- struct{ idx int; resp CPFResponse }{idx, CPFResponse{}}
return
}
ch <- struct{ idx int; resp CPFResponse }{idx, *resp}
}(i, cpf)
}
for range cpfs {
r := <-ch
resultados[r.idx] = r.resp
}
return resultados
}
Comparativo: net/http vs. resty
| Recurso | net/http | resty |
|---|---|---|
| Instalação | Nenhuma (stdlib) | go get |
| Retry automático | Manual | Integrado |
| Deserialização | Manual (json.Decode) | SetResult() |
| Configuração | Verbose | Fluente |
| Middleware | Manual | Integrado |
Boas práticas
-
Variáveis de ambiente -- Use
os.Getenv("CPFHUB_API_KEY"). -
Timeout -- Configure pelo menos 10 segundos para acomodar a latência média de ~900ms da API.
-
Reutilize o client -- Não crie um novo
http.Clientpor requisição. -
Goroutines -- Use para paralelismo em lotes, mas controle a concorrência para evitar custos inesperados com consultas extras.
-
Structs tipadas -- Defina structs para as respostas da API.
A documentação oficial do pacote net/http detalha opções avançadas de configuração de clientes HTTP, incluindo transports e proxies.
Perguntas frequentes
O que é necessário para consumir a API de CPF em Go?
Basta criar um http.Client com timeout adequado, configurar o header x-api-key com sua chave da CPFHub.io e fazer um GET para https://api.cpfhub.io/cpf/{CPF}. A resposta vem em JSON com nome, data de nascimento e gênero do titular. A latência média é de ~900ms, então configure o timeout com margem suficiente — 10 segundos é um valor seguro.
Qual a diferença prática entre net/http e resty para consumir APIs?
O net/http é a biblioteca padrão do Go, sem dependências externas, mas exige código mais verboso para deserialização, retries e configuração de headers. O resty é uma abstração que reduz esse boilerplate com interface fluente, retry automático e suporte a SetResult. Para projetos simples, net/http é suficiente; para produção com retry e timeouts finos, resty entrega mais com menos código.
Como a CPFHub.io trata o excedente de consultas?
A API não bloqueia quando o limite do plano é atingido. O plano gratuito inclui 50 consultas/mês e cada consulta adicional é cobrada a R$0,15. O plano Pro custa R$149/mês com 1.000 consultas incluídas e o mesmo valor por excedente. Isso significa que aplicações em Go que disparam goroutines em lote devem controlar a concorrência para evitar cobrança inesperada de excedentes.
Como usar goroutines com segurança ao consultar a API em lote?
Use um semáforo (canal com buffer) para limitar o número de goroutines simultâneas. Disparar centenas de requisições concorrentes aumenta o custo por consumir consultas além do plano. Um limite de 5 a 10 goroutines simultâneas já entrega bom desempenho sem risco de custo excessivo.
Conclusão
Go oferece ferramentas excelentes para consumir APIs de CPF: net/http para projetos sem dependências e resty para produção com retry e configuração fluente. Goroutines permitem processar lotes em paralelo com eficiência. A CPFHub.io
Cadastre-se em cpfhub.io
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.



