SDK Lua

SDK oficial para Lua 5.4+ com suporte a LuaJIT, coroutines e compatível com OpenResty / nginx.

Instalação

bash

luarocks install cpfhub

Requerimentos: Lua 5.4+ ou LuaJIT 2.1+, luasocket ou lua-http

Inicialização

Lua

local CPFHub = require("cpfhub")

local client = CPFHub.new({
  api_key = os.getenv("CPFHUB_API_KEY"),
  -- timeout = 10,   -- opcional, padrão: 10 segundos
})

Opções do construtor

Opção	Tipo	Padrão	Descrição
`api_key`	`string`	-	Sua API Key (obrigatório)
`timeout`	`number`	`10`	Timeout em segundos
`base_url`	`string`	`https://api.cpfhub.io`	URL base da API

Métodos

`client:lookup(cpf)`

Consulta um CPF e retorna os dados de identidade.

Lua

local ok, result = client:lookup("12345678909")

if ok then
  print(result.name)    -- "João da Silva"
  print(result.gender)  -- "M"
else
  print(result.code)    -- "CPF_NOT_FOUND"
end

Retorno: (true, data) em sucesso, (false, error) em erro

Lua

-- data
{
  cpf        = "12345678909",
  name       = "João da Silva",
  name_upper = "JOÃO DA SILVA",
  gender     = "M",          -- "M" | "F"
  birth_date = "15/04/1985", -- "DD/MM/AAAA"
  day        = 15,
  month      = 4,
  year       = 1985,
}

-- error
{
  code        = "CPF_NOT_FOUND",
  message     = "CPF not found in our database",
  status_code = 404,
}

Tratamento de erros

Lua

local ok, result = client:lookup("12345678909")

if not ok then
  if result.code == "CPF_NOT_FOUND" then
    print("CPF não encontrado")
  elseif result.code == "RATE_LIMIT_EXCEEDED" then
    print("Rate limit atingido - tente novamente em instantes")
  else
    print("Erro: " .. result.code)
  end
  return
end

print("Nome: " .. result.name)

Códigos de erro

`result.code`	`result.status_code`	Descrição
`CPF_NOT_FOUND`	`404`	CPF não encontrado (sem consumo de crédito)
`INVALID_CPF_FORMAT`	`400`	Formato inválido
`INVALID_CPF_DIGITS`	`422`	Dígitos verificadores inválidos
`MISSING_API_KEY`	`401`	API Key ausente
`INVALID_API_KEY`	`401`	API Key inválida
`RATE_LIMIT_EXCEEDED`	`429`	Limite de taxa excedido
`INSUFFICIENT_CREDITS`	`403`	Sem créditos disponíveis

Exemplos de integração

OpenResty / nginx

Lua

-- /etc/nginx/lua/cpf_lookup.lua
local CPFHub = require("cpfhub")
local cjson  = require("cjson")

local client = CPFHub.new({ api_key = os.getenv("CPFHUB_API_KEY") })

local function handler()
  local cpf = ngx.var.uri:match("/cpf/(%d+)")
  if not cpf then
    ngx.status = 400
    ngx.say(cjson.encode({ error = "CPF ausente" }))
    return
  end

  local ok, result = client:lookup(cpf)
  if ok then
    ngx.say(cjson.encode(result))
  else
    ngx.status = result.status_code
    ngx.say(cjson.encode({ error = result.code }))
  end
end

handler()

Script de linha de comando

Lua

#!/usr/bin/env lua
local CPFHub = require("cpfhub")

local client = CPFHub.new({ api_key = os.getenv("CPFHUB_API_KEY") })
local cpf    = arg[1]

if not cpf then
  print("Uso: lua consulta.lua <CPF>")
  os.exit(1)
end

local ok, result = client:lookup(cpf)
if ok then
  print(string.format("Nome: %s | Gênero: %s | Nascimento: %s",
    result.name, result.gender, result.birth_date))
else
  print("Erro: " .. result.code)
  os.exit(1)
end

Repositório e suporte

github.com/cpfhub/cpfhub-lua - código-fonte, issues e contribuições
LuaRocks: cpfhub - versões e changelog

Atualizado em 12 de maio de 2026