Configurar o Accelero — passo a passo

O que é este documento — o guia prático para conectar a controladora Accelero de uma escola ao ionCLASS: onde configurar, quais campos preencher, como testar a conexão (o "ping-pong") e o que fazer quando uma sincronização falha. Para o modelo conceitual (driver, identidade, fluxos), veja a visão geral.

Pré-requisitos

Antes de integrar, a escola já deve existir e estar ativa (veja Configuração inicial). A configuração da integração é por escola — repita para cada escola que tem hardware.

1. Onde fica a configuração

No Painel Administrativo, abra a escola e vá na aba Configurações, seção Integração com a catraca. É aqui que se escolhe o sistema de controle de acesso e se informam os endereços e segredos.

2. Preencher os dados da integração

Campo (rótulo no painel)	O que informar
Sistema de controle de acesso	Accelero para o hardware real (ou Nenhum (não integra) / mock)
URL do controle	O endereço da controladora/plugin Accelero da escola (ex.: https://controle.escola.com.br/ionclass, ou um IP na LAN da escola). Obrigatório para o Accelero.
Chave de eventos (entrada)	Segredo HMAC que o hardware usa para assinar os webhooks que envia ao ionCLASS. Use Gerar para criar uma.
Chave de comandos (saída)	Segredo HMAC que o ionCLASS usa para assinar os comandos que envia ao hardware. Use Gerar para criar uma.
Integração ativa	Liga a integração

As duas chaves são separadas e por direção, e ficam criptografadas no banco. O mesmo valor em claro precisa existir dos dois lados — copie as chaves geradas para a configuração do Accelero e use os mesmos valores nos dois lados. Deixe um campo de chave em branco para manter a atual. Ao final, clique em Salvar integração.

A escola só "integra" quando está ativa e tem URL do controle

Enquanto a integração não estiver ativa e (para o Accelero) sem URL do controle, o painel mostra o selo "Não integra" e o ionCLASS não envia nenhum comando ao hardware — não há fila outbound, não há liberação de catraca. Confirme os dois antes de esperar comportamento do hardware.

3. Testar a conexão ("ping-pong")

Depois de salvar, use o botão "Testar integração". Ele dispara um ping-pong que prova que os dois canais estão de pé:

1. ionCLASS  ──ping (assinado com a chave de saída)──►  Plugin Accelero      (FLUXO B)
2. Plugin    ──chama de volta o endpoint /ping (assinado com a chave de entrada)──►  ionCLASS   (FLUXO A)
3. ionCLASS  ──"pong: true"

• Se o ping-pong volta, os dois sentidos estão funcionando e com os tokens corretos.
• Se falha, verifique nesta ordem: URL do controle alcançável a partir do backend, chaves iguais dos dois lados, e a integração ativa.

4. Vincular leitores de chegada aos portões

Numa escola com mais de um portão, cada controladora de ponto de chegada (o leitor facial ou de placas onde o responsável é reconhecido ao chegar) fica num portão. Vincule cada uma ao seu portão para que a chegada lida nela apareça no quadro daquele portão no monitor da portaria.

1. No Accelero, marque as controladoras em "Controladores de ponto de chegada" (aba Canais da configuração do plugin ionCLASS). Só a chegada lida numa delas gera sinal.
2. No ionCLASS, abra Escolas → (escola) → Configurações → Leitores de chegada (a seção aparece quando a integração está ativa) e clique em "Sincronizar leitores". O ionCLASS busca a lista dessas controladoras no plugin.
3. Em cada leitor, escolha o portão onde ele fica. A mudança vale para a próxima chegada.

Como a chegada é resolvida:

• Leitor vinculado a um portão ativo → a chegada vai para esse portão.
• Leitor sem vínculo, vinculado a um portão desativado, ou plugin antigo que não informa o leitor → a chegada vai para o portão padrão, como antes.
• Se o responsável já avisou pelo app escolhendo um portão, vale o portão do app: o leitor só decide quando não houve aviso prévio.

Leitores novos aparecem sozinhos

Um leitor que ainda não foi sincronizado aparece na lista assim que alguém é lido nele, pronto para ser vinculado. Um leitor que some da lista do plugin não é apagado nem perde o vínculo: o painel só avisa que ele não veio na última sincronização.

"Atualize o plugin"

Se o botão responder que a controladora não conhece o comando, o plugin ionCLASS instalado no Accelero é anterior à versão 1.7.0. As chegadas continuam funcionando, sempre no portão padrão, até o plugin ser atualizado.

5. TLS em rede interna

A controladora costuma viver na LAN da escola, com IP privado e, muitas vezes, certificado não público. O ionCLASS trata isso assim:

• Para hosts internos/privados, a verificação de certificado TLS é pulada automaticamente — a autenticação real é o HMAC sobre o corpo, não o certificado.
• Para hosts públicos, o certificado é verificado normalmente.
• É possível forçar o comportamento com a variável de ambiente IONCLASS_OUTBOUND_VERIFY_TLS (padrão true).

6. Reenvio e retry (o que acontece quando falha)

Os comandos outbound (liberar/revogar pessoa, abrir catraca, espelhar veículo) passam por um livro-razão (ledger) durável com retry automático. Os parâmetros vivem na configuração de integração:

Parâmetro	Padrão	Env
Tentativas	3	IONCLASS_OUTBOUND_RETRIES
Backoff (segundos)	[60, 300, 900]	—
Timeout	30 s	IONCLASS_OUTBOUND_TIMEOUT_SECONDS
Verificar TLS	true	IONCLASS_OUTBOUND_VERIFY_TLS

Depois de esgotar as tentativas, a entidade afetada (ex.: uma pessoa autorizada) é marcada como pendência de sincronização e aparece no Painel para retry manual. A mesma chamada preserva o identificador de correlação (idempotência), então reenviar não duplica efeito no hardware.

7. Depois de integrar

Com a integração ativa e testada:

• Os eventos de catraca (entrada/saída) e a chegada facial de responsáveis passam a alimentar a retirada — ver Inbound.
• As aprovações (pessoa autorizada, saída antecipada) e a liberação da catraca do aluno pronto passam a ser enviadas ao hardware — ver Outbound.
• O roster do Accelero pode empurrar o cadastro de alunos — ver Alunos e responsáveis.

Ver também

• Visão geral da integração — driver, identidade e os dois fluxos
• Inbound · Outbound — o detalhe técnico de cada direção
• Modelo de domínio — onde a configuração da integração se encaixa