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.

Redação CPFHub.io
Redação CPFHub.io
··5 min de leitura
Como consumir APIs REST de CPF em Go usando 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)

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

Recursonet/httpresty
InstalaçãoNenhuma (stdlib)go get
Retry automáticoManualIntegrado
DeserializaçãoManual (json.Decode)SetResult()
ConfiguraçãoVerboseFluente
MiddlewareManualIntegrado

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 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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp