Integração com o Accelero

O que é este documento — o mapa único da integração entre o ionCLASS e o hardware de controle de acesso Accelero (catracas / portão / facial / LPR). Cobre a abstração de driver, o mapeamento de identidade entre os dois sistemas e as duas direções do tráfego. Para colocar a mão na massa, vá direto ao passo a passo de configuração.

O Accelero é o primeiro (e hoje único) driver de hardware, mas o design é agnóstico: novos provedores de controle de acesso podem ser plugados sem tocar no domínio.

A integração é opcional (mas recomendada)

Sem hardware integrado, o ionCLASS ainda funciona no modo operador/manual: o quadro de portaria conduz a retirada e a catraca não participa. Ao integrar o Accelero, a retirada ganha as leituras físicas (entrada/saída), a chegada por reconhecimento facial e a liberação automática da catraca.

1. Abstração de driver

Todo o domínio fala com o hardware através de um adaptador de controle de acesso agnóstico, nunca com o Accelero direto. Trocar/adicionar provedor é implementar esse adaptador e cadastrar a escola nele.

Peça	Papel
Adaptador de controle de acesso	Abstração agnóstica com as capacidades: checar conexão, receber evento do hardware, agendar visita, autorizar liberação, revogar visita e registrar/revogar veículo
Adaptador Accelero	Fala com a controladora Accelero via HTTP POST + assinatura HMAC-SHA256
Adaptador simulado (mock)	Dev/testes sem hardware real (não exige URL do controle)
Seleção por escola	Resolve qual sistema de controle de acesso responde por cada escola, a partir do que foi configurado
Configuração por escola	Sistema de controle de acesso, URL do controle, chave de eventos (entrada), chave de comandos (saída) e se está ativa

Configuração por escola

Uma configuração por escola — o sistema de controle de acesso não é global, é escolhido por escola. As duas chaves HMAC são separadas e por direção, armazenadas criptografadas:

• Chave de eventos (entrada) — verifica o FLUXO A (eventos/roster/veículos/ping vindos do hardware).
• Chave de comandos (saída) — assina o FLUXO B (comandos do backend para o hardware).

Uma escola só "integra" quando está ativa e, para o Accelero, tem a URL do controle preenchida. Sem isso, nenhuma chamada outbound é enfileirada — é o significado único de "escola não integrada" (não há fallback global).

2. Duas direções

 INBOUND  (FLUXO A)   Accelero  ──POST webhook (HMAC chave de entrada)──►  ionCLASS
                      catraca / facial / LPR                             events · roster · vehicles · ping

 OUTBOUND (FLUXO B)   ionCLASS  ──registro + entrega assíncrona + POST (HMAC chave de saída)──►  Accelero
                      aprovações / transições / sweeps                    agendar visita · autorizar liberação · revogar visita · veículos

• INBOUND — o hardware empurra fatos (aluno entrou/saiu, responsável chegou na portaria, cadastro/veículos, ping de saúde). O backend valida HMAC, deduplica, guarda o registro do evento recebido e aplica ao domínio numa fila.
• OUTBOUND — o backend empurra permissões (liberar/revogar pessoa, abrir a catraca do aluno pronto, espelhar veículo). Cada chamada é registrada num livro-razão (ledger) com um X-Correlation-Id idempotente e entregue de forma assíncrona com retry.

O tempo real do quadro da portaria (canal school.{id}.monitor) é consequência de eventos INBOUND/OUTBOUND, não um terceiro canal com o hardware — ver ciclo de retirada e runbook de tempo real.

3. Mapeamento de identidade

A chave de correlação entre os dois sistemas é a matrícula do aluno:

ionCLASS  matrícula do aluno   ==   student_external_id   ==   pesCodigo / education->id   Accelero

• Um evento de catraca chega com student_external_id; o backend resolve o aluno por matrícula (escopada à escola). O roster devolve o mapa matrícula → identificador (UUID) do aluno para o plugin manter seu identity map.
• O responsável NÃO viaja por matrícula. Numa chegada facial (guardian_arrival), o documento (CPF) vem no payload bruto (guardian_external_id) — nunca em student_external_id. A resolução do responsável é por CPF vinculado à escola.

4. Endpoints INBOUND (webhooks)

Todos POST, versionados v1, chaveados pela escola na URL, autenticados por HMAC-SHA256 com a chave de eventos (entrada). Detalhe em Inbound.

Endpoint	O que faz
api/v1/integrations/accelero/{school}/events	entry / exit / guardian_arrival → landing row + job assíncrono
api/v1/integrations/accelero/{school}/roster	Upsert de alunos/responsáveis; devolve o mapa matrícula → identificador (UUID) do aluno
api/v1/integrations/accelero/{school}/vehicles	Upsert/delete de um veículo do responsável (por CPF)
api/v1/integrations/accelero/{school}/ping	O "pong" do ping-pong de saúde (sem efeito)

5. Ações OUTBOUND (com ledger)

Toda ação passa pelo livro-razão (registrada e depois entregue de forma assíncrona com retry; no-op se a escola não integra) → comando para a controladora Accelero. Detalhe e gate LGPD em Outbound.

Ação	Quando dispara	Tipo Accelero
Agendar visita	Aprovação de pessoa autorizada / responsável / companion de passe	recurring_visit
Autorizar liberação (pontual)	Aprovação de saída antecipada (passe de retirada)	one_shot_release
Autorizar liberação (grant)	Aluno chega a ready (catraca default-deny)	immediate_release
Revogar visita	Bloqueio / suspensão / expiração / cancelamento; aluno saiu	revoke por visit_ref
Registrar / revogar veículo	CRUD de veículo do responsável	Cartão LPR

Gate de consentimento biométrico (LGPD art. 11)

Vive dentro do agendamento de visita: o rosto só é enviado quando a própria pessoa tem consentimento biométrico ativo; sem consentimento, a pessoa entra só com nome + CPF. Ver Outbound.

Ver também

• Configurar o Accelero (passo a passo) — o guia prático de configuração e teste
• Inbound — hardware → backend (webhooks, dedupe, roteamento por tipo)
• Outbound — backend → hardware (ledger, retry, gate LGPD, tipos)
• Ciclo de retirada — o ciclo de retirada e a corrida dual-source
• Glossário — termos (matrícula, sinal de chegada, estado de retirada…)