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. 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).

5. 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.

6. 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