Como consumir a API de CPF em Elixir usando HTTPoison e Tesla

Elixir oferece duas bibliotecas principais para consumir a API de CPF da CPFHub.io: HTTPoison, baseada em hackney, e Tesla, com seu sistema de middlewares plugáveis. Ambas realizam chamadas GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key e retornam o JSON com nome, data de nascimento e gênero do titular. A escolha entre elas depende do nível de composição necessário — o HTTPoison é mais direto, o Tesla oferece retry, logging e testabilidade com mock adapter nativo.

Introdução

Elixir oferece um ecossistema rico para comunicação HTTP, com duas bibliotecas principais: HTTPoison, baseada em hackney, e Tesla, que utiliza um sistema de middlewares plugáveis. Este artigo mostra como consumir a API da CPFHub.io utilizando ambas as abordagens, comparando suas características e ajudando você a escolher a melhor para cada cenário. A documentação oficial do HTTPoison está em hexdocs.pm/httpoison e a do Tesla em hexdocs.pm/tesla.

Configurando o projeto

Crie um novo projeto Elixir e adicione as dependências:

# mix.exs
defp deps do
    [
    {:httpoison, "~> 2.0"},
    {:tesla, "~> 1.8"},
    {:hackney, "~> 1.20"},
    {:jason, "~> 1.4"}
    ]
end

Execute mix deps.get para baixar as dependências. Ambas as bibliotecas suportam requisições assíncronas e tratamento de erros robusto.

Consumindo com HTTPoison

O HTTPoison é a biblioteca HTTP mais popular do Elixir. A consulta à API fica direta e concisa:

defmodule CpfHub.HTTPoisonClient do
    @base_url "https://api.cpfhub.io"

    def consultar(cpf, api_key) do
    headers = [
    {"x-api-key", api_key},
    {"Content-Type", "application/json"}
    ]

    case HTTPoison.get("#{@base_url}/cpf/#{cpf}", headers) do
    {:ok, %HTTPoison.Response{status_code: 200, body: body}} ->
    {:ok, Jason.decode!(body)}

    {:ok, %HTTPoison.Response{status_code: 401}} ->
    {:error, :chave_invalida}

    {:ok, %HTTPoison.Response{status_code: 404}} ->
    {:error, :cpf_nao_encontrado}

    {:ok, %HTTPoison.Response{status_code: status}} ->
    {:error, {:status_inesperado, status}}

    {:error, %HTTPoison.Error{reason: reason}} ->
    {:error, {:falha_rede, reason}}
    end
    end
end

Consumindo com Tesla

O Tesla oferece uma abordagem baseada em middlewares que permite compor funcionalidades como retry, logging e encoding de forma declarativa:

defmodule CpfHub.TeslaClient do
    use Tesla

    plug Tesla.Middleware.BaseUrl, "https://api.cpfhub.io"
    plug Tesla.Middleware.JSON
    plug Tesla.Middleware.Headers, [{"x-api-key", "SUA_API_KEY"}]
    plug Tesla.Middleware.Retry, delay: 1000, max_retries: 3
    plug Tesla.Middleware.Logger

    def consultar(cpf) do
    case get("/cpf/#{cpf}") do
    {:ok, %Tesla.Env{status: 200, body: body}} ->
    {:ok, body}

    {:ok, %Tesla.Env{status: 401}} ->
    {:error, :chave_invalida}

    {:ok, %Tesla.Env{status: 404}} ->
    {:error, :cpf_nao_encontrado}

    {:ok, %Tesla.Env{status: status}} ->
    {:error, {:status_inesperado, status}}

    {:error, reason} ->
    {:error, {:falha_requisicao, reason}}
    end
    end
end

Nota: a API da CPFHub.io nunca retorna HTTP 429. Ao atingir o limite mensal do plano, as consultas adicionais são cobradas a R$0,15 cada — sem bloqueio, sem interrupção de serviço. O middleware Retry acima é útil para erros de rede transitórios, não para limite de cota.

Comparação entre HTTPoison e Tesla

A escolha entre as duas bibliotecas depende das necessidades do projeto:

Criando um módulo unificado

Para flexibilidade, crie um behaviour que permite trocar a implementação HTTP:

defmodule CpfHub.Client do
    @callback consultar(cpf :: String.t()) :: {:ok, map()} | {:error, atom()}

    def new(api_key) do
    %{api_key: api_key}
    end

    def consultar_cpf(%{api_key: api_key}, cpf) do
    cpf_limpo = String.replace(cpf, ~r/\D/, "")

    if String.length(cpf_limpo) != 11 do
    {:error, :formato_invalido}
    else
    CpfHub.HTTPoisonClient.consultar(cpf_limpo, api_key)
    end
    end
end

# Uso
client = CpfHub.Client.new("SUA_API_KEY")

case CpfHub.Client.consultar_cpf(client, "123.456.789-00") do
    {:ok, %{"success" => true, "data" => dados}} ->
    IO.puts("Nome: #{dados["name"]}")
    IO.puts("CPF: #{dados["cpf"]}")
    IO.puts("Nascimento: #{dados["birthDate"]}")
    IO.puts("Gênero: #{dados["gender"]}")

    {:error, :cpf_nao_encontrado} ->
    IO.puts("CPF não encontrado na base")

    {:error, :chave_invalida} ->
    IO.puts("Verifique sua chave de API")

    {:error, reason} ->
    IO.puts("Erro: #{inspect(reason)}")
end

Perguntas frequentes

Qual biblioteca devo escolher para integrar a API de CPF em Elixir: HTTPoison ou Tesla?

Prefira o Tesla se o projeto já usa middleware de retry, logging centralizado ou precisa de mocks em testes. O HTTPoison é a escolha certa quando você quer uma integração simples, sem dependências extras de composição — basta um case no status code e você tem controle total. Ambos funcionam bem com a API da CPFHub.io.

Como testar a integração com a API de CPF sem fazer chamadas reais em Elixir?

Com Tesla, use Tesla.Mock no ambiente de teste: configure adapter: Tesla.Mock no módulo cliente e defina as respostas esperadas com Tesla.Mock.mock/1. Com HTTPoison, injete um módulo de adapter via configuração de ambiente (config :minha_app, :http_client, MyMockClient) e implemente um comportamento compartilhado entre o cliente real e o mock.

A API da CPFHub.io retorna HTTP 429 quando o limite do plano é atingido?

Não. A API da CPFHub.io nunca bloqueia nem retorna HTTP 429. Quando o limite mensal de consultas é ultrapassado, as requisições adicionais são processadas normalmente e cobradas a R$0,15 cada. Isso simplifica o tratamento de erros na sua aplicação Elixir — não é necessário implementar lógica de backoff para cota esgotada.

Como usar Oban para processar consultas de CPF em background no Elixir?

Crie um worker Oban que recebe o CPF e chama o CpfHub.Client.consultar_cpf/2. Configure a fila com concorrência adequada e use Oban.insert/1 nos pontos de entrada do sistema (cadastro de usuário, por exemplo). O Oban garante retry automático em caso de falha de rede, persistência no banco e visibilidade dos jobs via dashboard.

Conclusão

Tanto HTTPoison quanto Tesla são opções sólidas para consumir a API de CPF em Elixir. O HTTPoison é ideal para projetos que precisam de controle fino sobre as requisições, enquanto o Tesla brilha com seu sistema de middlewares e facilidade de teste.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a consultar CPFs na sua aplicação Elixir com a biblioteca que melhor se encaixa no seu stack.