Como integrar a API de CPF em Go: Guia prático

Bernardo Rocha

Publicado em 23 de abril de 2025

Introdução

A integração de uma API de consulta de CPF em aplicações desenvolvidas com Go (Golang) é essencial para empresas que precisam validar a identidade de clientes de forma rápida e segura. Essa funcionalidade é crucial para fintechs, bancos digitais, e-commerces e outras empresas que lidam com transações financeiras e cadastro de usuários.

Neste guia, você aprenderá a integrar a API da CPFHub.io em Go, utilizando a biblioteca

net/http

para fazer chamadas HTTP, garantindo que sua aplicação possa realizar consultas de CPF em tempo real de maneira eficiente e segura.

1. Pré-requisitos

Antes de iniciar, certifique-se de que você tem:

✅ Go instalado (versão 1.18 ou superior recomendada).
✅ Conta na CPFHub.io para obter a chave de API.
✅ Conhecimento básico sobre requisições HTTP em Go.

Se ainda não tem uma conta, cadastre-se em CPFHub.io e gere sua chave de API.

2. Criando um projeto em Go

Crie um diretório para seu projeto e inicialize um módulo Go:

mkdir cpf_consulta
cd cpf_consulta
go mod init cpf_consulta

3. Instalando dependências

O Go já possui suporte nativo para requisições HTTP com o pacote

net/http

, mas recomendamos a instalação do pacote

github.com/go-resty/resty/v2

para facilitar a manipulação de APIs.

Para instalar, execute:

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

4. Fazendo uma consulta de CPF com Go

Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com

net/http

Usando net/http

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

const apiKey = "SUA_CHAVE_DE_API"
const url = "https://api.cpfhub.io/api/cpf"

type CpfRequest struct {
    CPF       string `json:"cpf"`
    BirthDate string `json:"birthDate"`
}

type CpfResponse struct {
    Success bool `json:"success"`
    Data    struct {
        Name             string `json:"name"`
        Status           string `json:"status"`
        Situation        string `json:"situation"`
        BirthDate        string `json:"birthDate"`
        CPFNumber        string `json:"cpfNumber"`
        RegistrationDate string `json:"registrationDate"`
        Receipt         struct {
            EmissionTime string `json:"emissionTime"`
            EmissionDate string `json:"emissionDate"`
            ControlCode  string `json:"controlCode"`
        } `json:"receipt"`
    } `json:"data"`
}

func main() {
    requestData := CpfRequest{CPF: "123.456.789-00", BirthDate: "15/06/1990"}
    requestBody, _ := json.Marshal(requestData)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(requestBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Erro na requisição:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    var cpfResponse CpfResponse
    json.Unmarshal(body, &cpfResponse)

    if cpfResponse.Success {
        fmt.Println("CPF Válido:", cpfResponse.Data.Name)
    } else {
        fmt.Println("Erro na consulta de CPF")
    }
}

Usando Resty (alternativa simplificada)

package main

import (
    "fmt"
    "github.com/go-resty/resty/v2"
)

func main() {
    client := resty.New()
    
    response, err := client.R().
        SetHeader("Content-Type", "application/json").
        SetHeader("x-api-key", "SUA_CHAVE_DE_API").
        SetBody(map[string]string{
            "cpf": "123.456.789-00",
            "birthDate": "15/06/1990",
        }).
        Post("https://api.cpfhub.io/api/cpf")
    
    if err != nil {
        fmt.Println("Erro na consulta:", err)
        return
    }
    
    fmt.Println("Resposta da API:", response)
}

5. Exemplo de resposta da API

{
  "success": true,
  "data": {
    "name": "João da Silva",
    "status": "Regular",
    "situation": "Ativo",
    "birthDate": "15/06/1990",
    "cpfNumber": "12345678900",
    "registrationDate": "anterior a 10/11/1990",
    "verificationDigit": "03",
    "receipt": {
      "emissionTime": "22:08:26",
      "emissionDate": "13/01/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13012025&he=220826&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

Conclusão

Integrar a API de consulta de CPF em Go é um processo simples e eficiente, proporcionando mais segurança e agilidade na validação de identidade. Utilizando

net/http

resty

, sua aplicação pode realizar consultas em tempo real, garantindo conformidade com regulamentações e reduzindo riscos de fraude. Se sua empresa deseja uma solução confiável para validação de CPF, conheça a API da CPFHub.io e implemente uma integração robusta agora mesmo!