Tutorial de Integração

📋 Índice

1. Sobre a API HURU
2. Como Funciona
3. Primeiros Passos
4. Solicitar Código de Verificação
5. Verificar Código
6. Consultar Nível do Usuário
7. Exemplo Completo em PHP
8. Exemplo em JavaScript
9. Webhooks
10. Tabela de Níveis
11. Códigos de Erro

🔌 Sobre a API HURU

A API do HURU permite que sites e aplicações externas verifiquem a identidade de usuários de forma segura, utilizando o Registro Único Universal.

📌 Base URL: https://huru.forasteyros.org/api/

Endpoints disponíveis:

/externa.php - Para códigos de verificação (2FA)
/consultar-nivel.php - Para consultar nível do usuário

🔄 Como Funciona

Fluxo de Verificação de Identidade

Seu site pergunta ao usuário o Número de Registro HURU (ex: RUU-2024-XXXXXXXX-XXXX)
Seu site chama a API do HURU para solicitar um código para aquele registro
O usuário recebe uma notificação no site HURU com o código de 6 dígitos
O usuário informa o código no seu site
Seu site chama a API para verificar o código
Se válido, seu site prossegue com a ação (reset de senha, login, etc.)

🚀 Primeiros Passos

⚠️ Antes de começar: Você precisa solicitar uma API Key para seu domínio. Entre em contato com os administradores do HURU através do email: admin@huru.forasteyros.org

✅ O que você receberá:

API Key: Identificador único da sua aplicação
API Secret: Chave secreta para assinar requisições

📤 Solicitar Código de Verificação

Endpoint para solicitar um código de 6 dígitos para um usuário específico.

POST https://huru.forasteyros.org/api/externa.php?acao=solicitar_codigo

Headers

Content-Type: application/json
X-API-Key: SUA_API_KEY_AQUI
            

Body (JSON)

{
    "registro_unico": "RUU-2024-ABCDEF123456-ABCD",
    "tipo": "recuperacao_senha",
    "dados": {
        "motivo": "Recuperação de senha",
        "ip_usuario": "192.168.1.1"
    }
}
            

Resposta de Sucesso (200)

{
    "sucesso": true,
    "mensagem": "Código de verificação enviado",
    "dados": {
        "codigo_enviado": true,
        "expira_em": "2024-01-15 14:30:00"
    }
}
            

Resposta de Erro (400/403/404)

{
    "sucesso": false,
    "mensagem": "Registro não encontrado ou não verificado"
}
            

✅ Verificar Código

Endpoint para validar o código informado pelo usuário.

POST https://huru.forasteyros.org/api/externa.php?acao=verificar_codigo

Headers

Content-Type: application/json
X-API-Key: SUA_API_KEY_AQUI
            

Body (JSON)

{
    "registro_unico": "RUU-2024-ABCDEF123456-ABCD",
    "codigo": "123456"
}
            

Resposta de Sucesso (200)

{
    "sucesso": true,
    "mensagem": "Código válido",
    "dados": {
        "valido": true,
        "tipo": "recuperacao_senha",
        "dados_extras": {}
    }
}
            

Resposta de Erro (400)

{
    "sucesso": false,
    "mensagem": "Código inválido ou expirado"
}
            

📊 Consultar Nível do Usuário

Endpoint para consultar o nível de verificação de um usuário (requer autorização prévia do usuário).

POST https://huru.forasteyros.org/api/consultar-nivel.php?acao=consultar

Headers

Content-Type: application/json
X-API-Key: SUA_API_KEY_AQUI
            

Body (JSON)

{
    "registro_unico": "RUU-2024-ABCDEF123456-ABCD",
    "nivel_requerido": 3
}
            

Resposta de Sucesso (200)

{
    "sucesso": true,
    "mensagem": "Consulta realizada com sucesso",
    "dados": {
        "registro": "RUU-2024-ABCDEF123456-ABCD",
        "valido": true,
        "nivel_verificacao": 3,
        "nivel_nome": "Governamental",
        "trust_score": 75,
        "status_verificacao": "verificado",
        "atende_nivel_minimo_aplicacao": true,
        "nivel_suficiente": true,
        "nivel_requerido": 3
    }
}
            

💻 Exemplo Completo em PHP

solicitar_codigo.php

<?php
// solicitar_codigo.php - Solicitar código de verificação

function solicitarCodigoHURU($registroUnico, $apiKey) {
    $url = 'https://huru.forasteyros.org/api/externa.php?acao=solicitar_codigo';
    
    $payload = json_encode([
        'registro_unico' => $registroUnico,
        'tipo' => 'recuperacao_senha',
        'dados' => [
            'motivo' => 'Recuperação de senha',
            'ip_usuario' => $_SERVER['REMOTE_ADDR']
        ]
    ]);
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    
    $resposta = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return json_decode($resposta, true);
}

// Uso no seu site
$apiKey = 'SUA_API_KEY_AQUI';
$registro = $_POST['registro_ruu'] ?? '';

if ($registro) {
    $resultado = solicitarCodigoHURU($registro, $apiKey);
    
    if ($resultado['sucesso']) {
        $_SESSION['ruu_pendente'] = true;
        $_SESSION['ruu_registro'] = $registro;
        echo "<p>✅ Código enviado! Verifique suas notificações no site HURU.</p>";
    } else {
        echo "<p>❌ Erro: " . $resultado['mensagem'] . "</p>";
    }
}
?>
            

verificar_codigo.php

<?php
// verificar_codigo.php - Verificar código informado pelo usuário

function verificarCodigoHURU($registroUnico, $codigo, $apiKey) {
    $url = 'https://huru.forasteyros.org/api/externa.php?acao=verificar_codigo';
    
    $payload = json_encode([
        'registro_unico' => $registroUnico,
        'codigo' => $codigo
    ]);
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    
    $resposta = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($resposta, true);
}

// Processar formulário
$apiKey = 'SUA_API_KEY_AQUI';
$codigo = $_POST['codigo'] ?? '';
$registro = $_SESSION['ruu_registro'] ?? '';

if ($codigo && $registro) {
    $resultado = verificarCodigoHURU($registro, $codigo, $apiKey);
    
    if ($resultado['sucesso'] && $resultado['dados']['valido']) {
        // Código válido!
        $_SESSION['ruu_verificado'] = true;
        header("Location: redefinir_senha.php");
        exit;
    } else {
        echo "<p>❌ Código inválido ou expirado. Tente novamente.</p>";
    }
}
?>
            

🌐 Exemplo em JavaScript (Fetch API)

// solicitar_codigo.js - Solicitar código de verificação

const API_KEY = 'SUA_API_KEY_AQUI';
const BASE_URL = 'https://huru.forasteyros.org/api/';

async function solicitarCodigoHURU(registroUnico) {
    const response = await fetch(BASE_URL + 'externa.php?acao=solicitar_codigo', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        },
        body: JSON.stringify({
            registro_unico: registroUnico,
            tipo: 'recuperacao_senha',
            dados: {
                motivo: 'Recuperação de senha',
                user_agent: navigator.userAgent
            }
        })
    });
    
    return await response.json();
}

async function verificarCodigoHURU(registroUnico, codigo) {
    const response = await fetch(BASE_URL + 'externa.php?acao=verificar_codigo', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        },
        body: JSON.stringify({
            registro_unico: registroUnico,
            codigo: codigo
        })
    });
    
    return await response.json();
}

// Uso no frontend
document.getElementById('btnSolicitar').addEventListener('click', async () => {
    const registro = document.getElementById('registro_ruu').value;
    const resultado = await solicitarCodigoHURU(registro);
    
    if (resultado.sucesso) {
        alert('✅ Código enviado! Verifique suas notificações no site HURU.');
        document.getElementById('divCodigo').style.display = 'block';
    } else {
        alert('❌ Erro: ' + resultado.mensagem);
    }
});

document.getElementById('btnVerificar').addEventListener('click', async () => {
    const registro = document.getElementById('registro_ruu').value;
    const codigo = document.getElementById('codigo').value;
    const resultado = await verificarCodigoHURU(registro, codigo);
    
    if (resultado.sucesso && resultado.dados.valido) {
        alert('✅ Código válido! Redirecionando...');
        window.location.href = '/redefinir-senha';
    } else {
        alert('❌ Código inválido ou expirado');
    }
});
            

🔔 Webhooks

Registre um webhook para ser notificado quando o nível de um usuário mudar.

POST https://huru.forasteyros.org/api/consultar-nivel.php?acao=registrar-webhook

{
    "webhook_url": "https://seudominio.com/webhook-huru.php",
    "evento": "nivel_mudou"
}
            

Quando o nível do usuário mudar, enviaremos um POST para sua URL:

{
    "evento": "nivel_mudou",
    "usuario_id": 123,
    "nivel_anterior": 2,
    "nivel_novo": 3,
    "timestamp": "2024-01-15T10:30:00-03:00"
}
            

📊 Tabela de Níveis de Verificação

Nível	Nome	Verificações Necessárias	Indicado para
0	Básico	Email + Telefone	Fóruns, comentários
1	Documental	Selfie + Documento + Facial	Redes sociais, e-commerce
2	Financeiro	PIX + Cartão	Marketplaces, fintechs
3	Governamental	Gov.br + Receita	Serviços bancários
4	Biometria Digital	Fingerprint	Acesso sistemas críticos
5	Íris (Máximo)	Biometria de íris	Bancos, identidade oficial

⚠️ Códigos de Erro

Código	Significado	Solução
200	Sucesso	-
400	Requisição inválida	Verifique os parâmetros enviados
401	Não autorizado	Verifique sua API Key
403	Permissão negada	Usuário não autorizou o acesso
404	Registro não encontrado	Verifique o número de registro
429	Muitas requisições	Aguarde e tente novamente
500	Erro interno	Contate o suporte do HURU

🔒 Boas Práticas de Segurança

Nunca exponha sua API Key em código frontend (JavaScript do navegador)
Use HTTPS sempre em produção
Valide o domínio - A API só aceitará requisições de domínios autorizados
Armazene o número de registro HURU de forma segura no seu banco de dados
Expire a sessão após alguns minutos se o código não for verificado
Implemente rate limiting no seu lado também

📘 Tutorial de Integração - API HURU

📋 Índice

🔌 Sobre a API HURU

🔄 Como Funciona

Fluxo de Verificação de Identidade

🚀 Primeiros Passos

📤 Solicitar Código de Verificação

Headers

Body (JSON)

Resposta de Sucesso (200)

Resposta de Erro (400/403/404)

✅ Verificar Código

Headers

Body (JSON)

Resposta de Sucesso (200)

Resposta de Erro (400)

📊 Consultar Nível do Usuário

Headers

Body (JSON)

Resposta de Sucesso (200)

💻 Exemplo Completo em PHP

solicitar_codigo.php

verificar_codigo.php

🌐 Exemplo em JavaScript (Fetch API)

🔔 Webhooks

📊 Tabela de Níveis de Verificação

⚠️ Códigos de Erro

🔒 Boas Práticas de Segurança