Para: Suporte e TI

A vista Sincronização (administração e suporte) liga o MARCAR aos leitores e recebe os ficheiros. As credenciais de acesso aos leitores são instaladas no servidor pelo técnico de TI, nunca no ecrã; sem elas, o conector não pode ser activado. A instalação do servidor está em docs/ARRANQUE.md.

Os conectores passam nos testes com equipamento simulado, mas ainda não correram contra o equipamento real. No primeiro teste, confirme a direcção (entrada ou saída) e os tipos de evento.

Ligar um conector

Preencha as credenciais no .env do servidor e reinicie o servidor.
Em Conectores, prima Testar ligação. O teste mostra o número de série ou a versão, os eventos da última hora e as pessoas, e não grava nada.
Prima Activar, com motivo (só a administração activa).
Prima Reconciliar 7 dias para ler a última semana.

Depois disso, o ciclo automático (npm run sync) lê de 5 em 5 minutos, com sobreposição de 30 minutos, e reconcilia 7 dias uma vez por dia. Sincronizar agora força uma leitura. Em falhas seguidas, o ciclo recua até 1 hora e retoma sozinho.

Fontes suportadas
Fonte	Como se liga
Hikvision, terminal	ISAPI directo ao terminal, com utilizador e palavra-passe do terminal.
Hikvision, HikCentral Professional	Chave e segredo OpenAPI.
ZKTeco	O terminal liga-se ao receptor (`npm run adms`, porta 8081) e envia cada picagem na hora.
Suprema BioStar X	Servidor BioStar X da organização, com um utilizador só de leitura. O BioStar 2 não está incluído.
Entrada genérica	HTTP assinado, com um segredo por fonte.
CSV	Cadastro e picagens por ficheiro.

Terminais ZKTeco

No terminal: Comunicação → Servidor na nuvem (ADMS), com o IP do servidor e a porta.
O terminal aparece em Terminais ZKTeco como «por aprovar». Dê-lhe um nome e prima Aprovar terminal (administração).
Active o conector. Até estar activo, as picagens esperam na caixa de entrada e entram quando for activado.

Fontes de eventos (entrada genérica)

Para leitores de qualquer marca que enviem as picagens por um programa intermédio. Em Fontes de eventos, escreva o identificador (minúsculas, números, - e _; 3 a 32), o nome e o motivo, e prima Criar fonte. Cada fonte tem o seu segredo, que aparece uma só vez: copie-o logo para o programa que envia e prima Já copiei, esconder.

Rodar segredo cria um segredo novo (o antigo deixa de valer).
Revogar fonte corta a fonte de imediato. Use-o se suspeitar que o segredo foi comprometido.
Os pedidos levam assinatura, um valor único (nonce) e a hora; o relógio do emissor tem de estar certo (margem de 5 minutos).

Importações e execuções

As importações de cadastro e de picagens por CSV estão nos capítulos Preparar e Receber as picagens. Em Últimas execuções vê cada sincronização, com o estado e o último erro. Enquanto uma sincronização está a correr, a vista actualiza-se de 5 em 5 segundos.

Erros que aparecem

Códigos de erro habituais dos conectores
Código	Significado e acção
`AUTENTICACAO_EQUIPAMENTO`	Utilizador ou palavra-passe do leitor errados. Corrija no `.env`.
`EQUIPAMENTO_SEM_RESPOSTA`	Problema de rede entre o servidor e o leitor.
`BIOSTAR_EXIGE_HTTPS`	O BioStar X só aceita ligação segura.
`CONECTOR_OCUPADO`	Outra sincronização em curso; resolve-se sozinho.
`RELOGIO_FORA_DA_JANELA`	O relógio de quem envia está desfasado mais de 5 minutos. Acerte-o.

A lista completa e o procedimento para cada incidente (aplicação, base de dados, disco, cópias de segurança) estão no docs/RUNBOOK.md.

Suporte e TI: sincronização e conectores