Élleva DEVELOPERS

Integre qualquer coisa ao Élleva.

Catraca, leitor QR/RFID/NFC, câmera de reconhecimento facial, cancela veicular, interfone IP ou o seu sistema interno. Se fala HTTP, conecta — com chave individual por dispositivo, validação de acesso em milissegundos e webhooks assinados.

🔑 Chave por dispositivo ⚡ Resposta < 100 ms 📡 Heartbeat + online 🪝 Webhooks HMAC SHA-256 📖 OpenAPI 3.0 🆔 Correlation ID em tudo

Quickstart — catraca conectada em 3 passos

Do zero ao primeiro acesso validado em menos de 10 minutos.

1

Cadastre o dispositivo

No painel, em Operação → Dispositivos → Cadastrar dispositivo, registre a catraca/leitor com nome, categoria e local. Anote o device_id exibido no detalhe.

2

Gere a chave do dispositivo

Com seu token de admin, chame POST /api/integrations/devices passando o device_id. A resposta traz a device_key (formato edk_…) — ela aparece uma única vez; configure-a no equipamento.

3

Aponte o equipamento

Configure o firmware/middleware para chamar POST /api/access/validate com header X-Device-Key a cada leitura de credencial. A resposta {allow:true|false} aciona o relé.

# 1) Login (pega o JWT — campo é "senha", em português)
curl -X POST https://elleva.app.br/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"voce@condominio.com","senha":"SuaSenha"}'

# 2) Gera a chave individual do dispositivo (admin)
curl -X POST https://elleva.app.br/api/integrations/devices \
  -H 'Authorization: Bearer SEU_JWT' -H 'Content-Type: application/json' \
  -d '{"device_id":"catraca-portaria-1","name":"Catraca da portaria"}'
# → {"ok":true,"device_key":"edk_ab12cd34ef56gh78.0123456789abcdef…"}

# 3) O equipamento valida cada credencial lida
curl -X POST https://elleva.app.br/api/access/validate \
  -H 'X-Device-Key: edk_ab12cd34ef56gh78.0123…' -H 'Content-Type: application/json' \
  -d '{"credential_type":"qr","credential":"GUE-X9K2-AB3F","area":"salao"}'
# → {"allow":true,"reason":"convidado autorizado","profile":{"name":"Ana","kind":"convidado"}}
// Node.js 18+ (fetch nativo) — middleware da catraca
const ELLEVA = 'https://elleva.app.br/api';
const DEVICE_KEY = process.env.ELLEVA_DEVICE_KEY; // edk_…

async function validarAcesso(credential, area) {
  const r = await fetch(ELLEVA + '/access/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Device-Key': DEVICE_KEY },
    body: JSON.stringify({ credential_type: 'qr', credential, area })
  });
  const data = await r.json();
  if (data.allow) abrirRele();          // GPIO / Wiegand out
  return data;                          // {allow, reason, profile}
}

// Heartbeat a cada 60 s — o painel mostra o dispositivo ONLINE
setInterval(() => fetch(ELLEVA + '/integrations/heartbeat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Device-Key': DEVICE_KEY },
  body: JSON.stringify({ firmware: '1.4.2' })
}), 60000);
# Python 3 — middleware da catraca (requests)
import os, time, requests

ELLEVA = 'https://elleva.app.br/api'
HEADERS = {'X-Device-Key': os.environ['ELLEVA_DEVICE_KEY']}

def validar_acesso(credential, area=''):
    r = requests.post(f'{ELLEVA}/access/validate', headers=HEADERS, json={
        'credential_type': 'qr', 'credential': credential, 'area': area
    }, timeout=5)
    data = r.json()
    if data['allow']:
        abrir_rele()                       # GPIO.output(RELE, HIGH)
    return data

def heartbeat():
    requests.post(f'{ELLEVA}/integrations/heartbeat', headers=HEADERS,
                  json={'firmware': '1.4.2'}, timeout=5)

while True:
    heartbeat(); time.sleep(60)

Autenticação — 3 níveis de chave

Cada integração usa o nível certo de privilégio. Revogar um dispositivo nunca derruba os outros.

🔑 JWT (usuário)

Authorization: Bearer <jwt>

Obtido em POST /auth/login (+ MFA quando habilitado). Vale 8 h. Usado por apps, painéis e gestão das integrações. Permissões seguem o papel do usuário (RBAC).

🤖 X-API-Key (serviço)

X-API-Key: <chave mestra>

Chave server-to-server da plataforma. Acesso amplo — use apenas em backends confiáveis, nunca em firmware de campo. Disponível em Configurações → API & Webhooks.

🚪 X-Device-Key (dispositivo)

X-Device-Key: edk_…

Chave INDIVIDUAL por equipamento, com escopo restrito (validar acesso, heartbeat, eventos). Vaza uma catraca? Revoga só ela em DELETE /integrations/devices/{id}.

Boas práticas: grave a device_key na configuração do equipamento (ou no middleware local), nunca em código-fonte versionado. Toda resposta da API carrega X-Request-Id: EVA-XXXX-XXXX-XXXX — registre-o nos seus logs para suporte instantâneo.

Referência de endpoints

Base: https://elleva.app.br/api · Spec completa: openapi.json

MétodoEndpointAuthO que faz
GET/healthSaúde da API (status, hora, request_id)
POST/auth/loginLogin. Body {email, senha}. Pode responder mfa_required
POST/auth/mfa/verifyConfirma OTP de 6 dígitos; trust_device:true emite token de 30 dias
GET/store/bootstrapJWTHidrata todas as coleções do tenant em 1 chamada
POST/store/{coll}JWTCria/atualiza documento. Dispara notificações e webhooks
POST/access/validateDevice/API keyValidação de acesso: morador, convidado (janela da reserva) e Gestão Parental (área+horário)
POST/integrations/devicesJWT adminGera chave individual edk_… para um dispositivo
GET/integrations/devicesJWT adminLista chaves (mascaradas) com último uso
DEL/integrations/devices/{id}JWT adminRevoga a chave de um dispositivo
POST/integrations/heartbeatDevice keyPing de vida — painel mostra dispositivo online
POST/integrations/eventsDevice keyIngestão de evento bruto {type, payload} (porta abriu, alarme, falha)
GET/integrations/webhooksJWT adminLista assinaturas de webhook de saída + catálogo de eventos
PUT/integrations/webhooksJWT adminDefine webhooks [{url, secret, events[]}]
POST/integrations/webhooks/testJWT adminDispara entrega de teste para todas as URLs ativas
GET/integrations/deliveriesJWT adminHistórico das últimas 100 entregas (código HTTP, ok, detalhe)
GET/notifications/eventsJWTCatálogo dos 17 eventos com regras ativas
GET/metricsJWTKPIs agregados da plataforma

Integração de hardware — o fluxo completo

O Élleva é hardware-agnóstico por design: a decisão de acesso vive no nosso backend, e o equipamento só pergunta. Trocar de catraca = reconfigurar 1 URL.

📷
1. LeituraCatraca/leitor lê QR, NFC, RFID, facial ou placa
📡
2. PerguntaPOST /access/validate com X-Device-Key
🧠
3. DecisãoMorador ativo? Convidado na janela? Menor com permissão da Gestão Parental?
🚪
4. Ação{allow:true} → relé abre. Tudo auditado + pais notificados
Protocolos suportados na ponta: HTTP webhook (nativo) · Wiegand 26/34 (via conversor/middleware) · ONVIF (câmeras enviam o score/template para o middleware chamar a API) · TCP/IP relé seco (cancelas). Qualquer equipamento de qualquer fabricante que consiga fazer uma chamada HTTP — direta ou via um Raspberry Pi/mini-PC de ponte — funciona.
# Resposta do /access/validate — campos que o seu firmware usa
{
  "allow": true,                          // abre ou não o relé
  "reason": "convidado autorizado",      // para display/log local
  "profile": {
    "name": "Ana Silva",                 // exibir no display da portaria
    "unidade": "1502B",
    "kind": "convidado"                  // morador | convidado | menor
  },
  "at": "2026-06-11T15:32:08-03:00",
  "request_id": "EVA-9APN-3CBD-G46E"     // guarde no log do device
}

Webhooks de saída — eventos em tempo real no seu sistema

Todo evento da plataforma (reserva confirmada, acesso de menor, encomenda, multa…) pode ser entregue à sua URL, assinado com HMAC SHA-256. Ideal para BI, ERP da administradora, sistemas de segurança.

# 1) Inscreva sua URL (admin)
curl -X PUT https://elleva.app.br/api/integrations/webhooks \
  -H 'Authorization: Bearer SEU_JWT' -H 'Content-Type: application/json' \
  -d '{"webhooks":[{"url":"https://seu-sistema.com/elleva-hook","secret":"sua-chave-secreta","events":["reserva.confirmada","parental.alerta"]}]}'
# events: lista específica ou omita para receber TODOS ("*")

# 2) O Élleva entrega assim:
POST https://seu-sistema.com/elleva-hook
X-Elleva-Signature: sha256=3f1a9c…        # HMAC_SHA256(body, secret)
X-Elleva-Event: reserva.confirmada
X-Elleva-Delivery: dlv_ab12cd34

{"event":"reserva.confirmada","tenant":"rv","at":"2026-06-11T18:40:00-03:00","data":{…}}
import crypto from 'node:crypto';

app.post('/elleva-hook', (req, res) => {
  const esperado = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
                                     .update(req.rawBody).digest('hex');
  const recebido = req.get('X-Elleva-Signature') || '';
  if (!crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido)))
    return res.status(401).end();      // assinatura inválida → descarte
  processar(req.body);                   // seguro: veio do Élleva
  res.status(200).end();
});
import hmac, hashlib

def verificar(body_bytes: bytes, assinatura: str, secret: str) -> bool:
    esperado = 'sha256=' + hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, assinatura or '')

# Flask: verificar(request.get_data(), request.headers.get('X-Elleva-Signature'), SECRET)
$body = file_get_contents('php://input');
$esperado = 'sha256=' . hash_hmac('sha256', $body, $_ENV['WEBHOOK_SECRET']);
$recebido = $_SERVER['HTTP_X_ELLEVA_SIGNATURE'] ?? '';
if (!hash_equals($esperado, $recebido)) { http_response_code(401); exit; }
$evento = json_decode($body, true);   // seguro: veio do Élleva
Confiabilidade: cada entrega tem X-Elleva-Delivery único — use-o para deduplicar. Responda 2xx em até 5 s. Consulte falhas em GET /integrations/deliveries. Teste tudo com POST /integrations/webhooks/test.

Erros e suporte

Toda resposta de erro é JSON estruturado com correlation ID — encaminhe-o ao suporte e localizamos a requisição exata nos logs.

{
  "error": "X-Device-Key inválida ou revogada.",
  "kind": "unauthorized",
  "request_id": "EVA-PP8D-C3YA-9Y88",
  "support_email": "contato@luizrjesus.com.br"
}
HTTPkindQuando
400client_errorBody malformado, campo obrigatório ausente
401unauthorizedToken/chave ausente, inválida ou expirada
403forbiddenSem permissão (RBAC ou cross-tenant)
429client_errorRate limit (ex.: reenvio de MFA antes de 60 s)
5xxserver_errorFalha interna — sempre com request_id para suporte

Pronto para plugar?

Cadastre o primeiro dispositivo na demonstração ou fale com a gente para um piloto guiado.

Abrir a demonstração Falar com o time