Como consumir API de CPF em Lua para sistemas de jogos e IoT

Consumir a API de CPF em Lua é viável tanto em servidores de jogos online quanto em dispositivos IoT como NodeMCU e ESP32. Use a biblioteca lua-requests para ambientes com LuaRocks disponível, LuaSocket com LuaSec para HTTPS em ambientes restritos, ou io.popen com cURL em dispositivos embarcados. A ANPD orienta que dados pessoais como CPF sejam tratados com o princípio da necessidade — colete e armazene apenas o que for imprescindível para a operação.

Introdução

O Lua é uma linguagem de programação leve, rápida e embarcável, amplamente utilizada em três domínios principais: jogos (como motor de script em engines como Roblox, Love2D e Corona SDK), IoT (em dispositivos embarcados com NodeMCU e ESP8266) e sistemas de rede (como scripts em Nginx via OpenResty). No Brasil, a demanda por validação de CPF em plataformas de jogos online e apostas vem crescendo significativamente, especialmente com a regulamentação do setor de betting.

1. Pré-requisitos

Dependendo do seu ambiente, você precisará de:

• Lua 5.3 ou superior -- Ou LuaJIT para melhor performance.

• LuaRocks -- Gerenciador de pacotes para instalar bibliotecas.

• Conta na CPFHub.io -- Cadastre-se em CPFHub.io e gere sua chave de API no painel.

Instalando bibliotecas necessárias

luarocks install lua-requests
luarocks install luasocket
luarocks install lua-cjson

2. Consumindo a API com lua-requests

A biblioteca lua-requests oferece uma interface inspirada na popular biblioteca requests do Python:

local requests = require('requests')
local cjson = require('cjson')

local cpf = '12345678900'
local api_key = 'SUA_CHAVE_DE_API'
local url = 'https://api.cpfhub.io/cpf/' .. cpf

local response = requests.get(url, {
    headers = {
    ['x-api-key'] = api_key,
    ['Accept'] = 'application/json',
    },
    timeout = 30,
})

if response.status_code == 200 then
    local data = cjson.decode(response.text)

    if data.success then
    print('Nome: ' .. data.data.name)
    print('Nome (maiusculas): ' .. data.data.nameUpper)
    print('Genero: ' .. data.data.gender)
    print('Nascimento: ' .. data.data.birthDate)
    print('Dia: ' .. data.data.day .. ', Mes: ' .. data.data.month .. ', Ano: ' .. data.data.year)
    else
    print('Consulta nao retornou dados.')
    end
else
    print('Erro HTTP: ' .. response.status_code)
end

3. Consumindo a API com LuaSocket e LuaSec

Para ambientes onde lua-requests não está disponível, use LuaSocket com LuaSec para suporte HTTPS:

local https = require('ssl.https')
local ltn12 = require('ltn12')
local cjson = require('cjson')

local cpf = '12345678900'
local api_key = 'SUA_CHAVE_DE_API'
local url = 'https://api.cpfhub.io/cpf/' .. cpf

local response_body = {}

local result, status_code, headers = https.request({
    url = url,
    method = 'GET',
    headers = {
    ['x-api-key'] = api_key,
    ['Accept'] = 'application/json',
    ['Content-Length'] = '0',
    },
    sink = ltn12.sink.table(response_body),
    timeout = 30,
})

if status_code == 200 then
    local body = table.concat(response_body)
    local data = cjson.decode(body)

    if data.success then
    local info = data.data
    print('Nome: ' .. info.name)
    print('CPF: ' .. info.cpf)
    print('Genero: ' .. info.gender)
    print('Nascimento: ' .. info.birthDate)
    else
    print('Consulta sem sucesso.')
    end
else
    print('Erro HTTP: ' .. tostring(status_code))
end

4. Abordagem via cURL para ambientes restritos

Em dispositivos IoT ou ambientes embarcados onde instalar bibliotecas Lua pode não ser viável, use o cURL via os.execute ou io.popen:

local cjson = require('cjson')

local cpf = '12345678900'
local api_key = 'SUA_CHAVE_DE_API'

local comando = string.format(
    'curl -s -X GET "https://api.cpfhub.io/cpf/%s" '
    .. '-H "x-api-key: %s" '
    .. '-H "Accept: application/json" '
    .. '--max-time 30',
    cpf, api_key
)

local handle = io.popen(comando)
local resultado = handle:read('*a')
handle:close()

if resultado and #resultado > 0 then
    local data = cjson.decode(resultado)

    if data.success then
    print('Nome: ' .. data.data.name)
    print('Genero: ' .. data.data.gender)
    print('Nascimento: ' .. data.data.birthDate)
    else
    print('Consulta sem sucesso.')
    end
else
    print('Erro ao executar cURL.')
end

5. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com os dados do titular:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success -- Indica se a consulta foi realizada com sucesso.
• name / nameUpper -- Nome completo do titular em formato padrão e maiúsculas.
• gender -- Gênero do titular (M ou F).
• birthDate -- Data de nascimento completa.
• day, month, year -- Componentes da data separados, úteis para verificação de idade.

6. Caso de uso -- Verificação de idade em jogos e apostas

Com a regulamentação de apostas no Brasil, plataformas de betting e jogos online precisam verificar se o jogador tem 18 anos ou mais. A API da CPFHub.io retorna a data de nascimento, permitindo essa validação:

local cjson = require('cjson')

function verificar_idade_minima(data_api, idade_minima)
    local ano_atual = tonumber(os.date('%Y'))
    local mes_atual = tonumber(os.date('%m'))
    local dia_atual = tonumber(os.date('%d'))

    local idade = ano_atual - data_api.year
    if mes_atual < data_api.month then
    idade = idade - 1
    elseif mes_atual == data_api.month and dia_atual < data_api.day then
    idade = idade - 1
    end

    return idade >= idade_minima
end

-- Exemplo de uso com dados da API
local dados_jogador = {
    name = 'Joao da Silva',
    day = 15,
    month = 6,
    year = 1990,
}

if verificar_idade_minima(dados_jogador, 18) then
    print('Jogador autorizado: maior de 18 anos.')
else
    print('Jogador nao autorizado: menor de 18 anos.')
end

7. Caso de uso -- Validação em dispositivos IoT

Em sistemas IoT com NodeMCU ou ESP32 rodando Lua, a validação de CPF pode ser útil em terminais de autoatendimento, catracas inteligentes ou totens de cadastro:

• Totem de cadastro -- Validar o CPF informado pelo usuário antes de emitir um crachá ou liberar acesso.

• Catraca inteligente -- Confirmar a identidade do visitante em portarias automatizadas.

• Terminal de ponto -- Verificar dados do funcionário durante o registro de ponto eletrônico.

Para esses cenários, a abordagem via cURL com io.popen é a mais adequada, dado o ambiente restrito dos dispositivos embarcados.

8. Boas práticas

• Defina timeouts adequados -- Em ambientes IoT, a conectividade pode ser instável. Configure timeouts generosos para evitar falhas.

• Implemente cache local -- Armazene resultados em tabelas Lua ou arquivos temporários para reduzir chamadas à API.

• Valide o CPF localmente -- Antes de consultar a API, verifique se o CPF possui 11 dígitos e se os dígitos verificadores são válidos.

• Respeite os rate limits -- O plano gratuito permite 1 requisição a cada 2 segundos. O plano Pro (R$ 149/mês) permite 1 requisição por segundo.

Perguntas frequentes

Quais bibliotecas Lua são recomendadas para consumir a API de CPF?

Para ambientes completos com LuaRocks, lua-requests é a opção mais simples — a interface é similar ao requests do Python. Em ambientes sem LuaRocks, use LuaSocket com LuaSec para suporte a HTTPS. Em dispositivos IoT restritos como NodeMCU, a abordagem via io.popen com cURL é a mais confiável por não exigir instalação de bibliotecas adicionais.

A API de CPF funciona em dispositivos IoT com conectividade instável?

Sim, mas exige configuração cuidadosa de timeout e retry. Configure --max-time 30 no cURL e implemente uma função de retry com backoff exponencial para lidar com falhas de rede. Para dispositivos com memória muito limitada, armazene o resultado da consulta localmente e reutilize durante a sessão — assim uma queda de conexão não interrompe o fluxo completo.

Como validar a maioridade de jogadores usando a API de CPF em Lua?

A API retorna day, month e year separados, o que simplifica o cálculo de idade em Lua. Compare o ano atual com o ano de nascimento, ajuste para meses e dias, e verifique se o resultado é >= 18. Veja o exemplo completo na seção 6 deste artigo. Esse fluxo atende ao requisito de verificação de maioridade exigido pela regulamentação brasileira de apostas esportivas.

É possível usar a API CPFHub.io em servidores de jogos Roblox ou Love2D?

Em Roblox, o acesso a APIs externas é feito via HttpService:GetAsync no lado servidor (Script, não LocalScript). A chamada deve incluir o header x-api-key e respeitar as políticas de HTTPS do Roblox. Em Love2D com LuaJIT, use lua-requests ou LuaSocket normalmente. Em ambos os casos, nunca exponha a chave de API no cliente — mantenha as chamadas no servidor.

Conclusão

Consumir a API de consulta de CPF em Lua é viável em diferentes cenários, desde servidores de jogos online até dispositivos IoT. As bibliotecas lua-requests e LuaSocket oferecem interfaces práticas para requisições HTTP, enquanto a abordagem via cURL atende ambientes mais restritos.

A CPFHub.io oferece latência de ~900ms, SLA de 99,9% e plano gratuito com 50 consultas mensais — suficiente para validar identidades em protótipos IoT e jogos em desenvolvimento sem custo inicial.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.