CPFHub.io
Começar grátis

Consultar CPF com Go

Consulte CPF com Go usando net/http da biblioteca padrão. Sem dependências externas.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta Simples e cole no seu assistente.

Abrir no Cursor

Antes de começar

  1. Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
  2. Copie sua API Key em app.cpfhub.io/api-keys.
  3. Guarde a chave em uma variável de ambiente, nunca no código:
bash
export CPFHUB_API_KEY="sua_api_key"

Exemplo

Go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

type resposta struct {
	Data *struct {
		Name      string `json:"name"`
		BirthDate string `json:"birthDate"`
	} `json:"data"`
	// error vem como texto ("...") ou como objeto ({"message": "..."})
	Error json.RawMessage `json:"error"`
}

func main() {
	cpf := "12345678909"

	req, err := http.NewRequest(http.MethodGet, "https://api.cpfhub.io/cpf/"+cpf, nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", os.Getenv("CPFHUB_API_KEY"))

	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var body resposta
	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
		log.Fatal(err)
	}

	switch resp.StatusCode {
	case http.StatusOK:
		fmt.Println(body.Data.Name, body.Data.BirthDate)
	case http.StatusNotFound:
		fmt.Println("CPF não encontrado (não consome crédito)")
	case http.StatusTooManyRequests:
		fmt.Println("Limite por minuto atingido. Tente de novo em", resp.Header.Get("Retry-After"), "s")
	default:
		log.Fatalf("Erro %d: %s", resp.StatusCode, body.Error)
	}
}

Salve como main.go e rode com go run main.go.

Resposta

CPF encontrado (200, consome 1 crédito):

JSON
{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

CPF não encontrado (404, não consome crédito):

JSON
{
  "success": false,
  "data": null,
  "error": { "message": "CPF não encontrado na base de dados" }
}

O CPF 12345678909 é fictício, usado só nos exemplos. gender pode vir null.

Erros

StatusO que significaO que fazer
404CPF não está na baseTrate como "não encontrado". Não consome crédito.
400 / 422CPF sem 11 dígitos ou com dígito verificador inválidoCorrija a entrada. Não consome crédito.
401API Key ausente ou inválidaConfira a variável CPFHUB_API_KEY.
403Créditos esgotados ou conta inativaVeja o saldo em GET /quota ou recarregue no dashboard.
429Limite de requisições por minutoEspere os segundos do header Retry-After e tente de novo.
5xxFalha temporáriaTente de novo após alguns segundos.

O campo error pode vir como texto ("error": "...") ou como objeto ("error": { "message": "..." }), conforme o status. Os exemplos acima tratam os dois formatos. Lista completa em Códigos de Erro.

Próximos passos