# Como consumir APIs REST de CPF em Go usando net/http e resty

> Aprenda a consumir APIs REST de CPF em Go usando net/http e resty. Exemplos práticos, tratamento de erros e goroutines para paralelismo.

**Publicado:** 21/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-apis-rest-de-cpf-em-go-com-net-http-e-resty

---

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)

```go
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

```bash
go get github.com/go-resty/resty/v2
```

### Consulta com resty

```go
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

```go
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.Client` por 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](https://pkg.go.dev/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.

### 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 consumir API de CPF em Go com net/http e tratamento de erros](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-go-com-net-http-e-tratamento-de-erros)
- [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)

---

## 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**](https://www.cpfhub.io/)

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