akitasoft-layers-api

mateusroerig

Guia de Configuração — Integração Akita Soft × Layers

O que é esta aplicação?

A akitasoft-layers-api é uma API intermediária que conecta o Akita Soft à plataforma educacional Layers. Ela permite que responsáveis visualizem os registros de entrada e saída dos alunos diretamente no aplicativo da Layers e também recebam notificações sobre as entradas e saídas dos alunos.

Passo 1 — Criar o arquivo de configuração

A aplicação não armazena configurações sensíveis no WAR. É necessário criar um arquivo externo no servidor.

Crie o arquivo no seguinte caminho (substitua <usuario> pelo usuário do sistema que executa o Tomcat):

/home/<usuario>/.grails/akitasoft-layers-apiConfig/application.yml

Crie os diretórios se necessário:

mkdir -p /home/<usuario>/.grails/akitasoft-layers-apiConfig

Passo 2 — Preencher o arquivo de configuração

Cole o conteúdo abaixo no arquivo criado e preencha os valores indicados:

# Conexão com o banco de dados Oracle (Akita Soft)
dataSource:
  url: jdbc:oracle:thin:@<host>:<porta>:<sid>
  username: '<usuario_banco>'
  password: '<senha_banco>'

# Configurações da integração com a Layers
layers:
  apiUrl: https://api.layers.digital
  secret: '<secret_fornecido_pela_layers>'               # Deve ser gerado no ambiente da Layers e configurado aqui para autenticação
  accessToken: '<token_de_acesso_fornecido_pela_layers>' # Deve ser gerado no ambiente da Layers e configurado aqui para autenticação
  communityId: '<id_da_comunidade_na_layers>'            # Localizado no ambiente da Layers, necessário para associar os acessos à comunidade correta

# Configurações de comportamento da API
api:
  acessos:
    codIntegracao:
      paddingSize: 0      # Largura do zero-padding do alias enviado à Layers (0 = sem padding; ex: 6 transforma "42" em "000042")
    filtro:
      tipoPessoa: ''      # Deixar vazio para não filtrar, ou informar os tipos pessoas que devem ser considerados na busca dos acessos (ex: '1,2,3')
      diasRetroativos: 90 # Quantos dias anteriores de acesso serão retornados para os responsáveis
      minutosRetroativos: 10 # Quantos minutos antes do updatedAfter a consulta de acessos pendentes deve recuar (Fluxo 2)
    job:
      intervaloMinutos: 1  # intervalo em minutos do job de publicação de novos acessos

Atenção: o arquivo deve ser salvo com encoding UTF-8 e indentação com espaços (não use Tab).

Passo 3 — Configurações no sistema

Antes de ativar a integração, os cadastros nos dois sistemas devem estar alinhados. A API utiliza o campo cod_integracao do Akita Soft como chave de vínculo com o alias do aluno na Layers.

Akita Soft

3.1 — Vincular alunos à Layers

Para cada aluno que deve ser integrado, o campo cod_integracao na tabela controles_pessoas deve estar preenchido com o alias do aluno cadastrado na Layers.

Alunos com cod_integracao nulo são ignorados pela integração.

3.2 — Configurar os relógios de acesso

A integração considera somente acessos registrados em relógios marcados como "Saída de empresa" (campo saida_empresa = 'S' na tabela relogios_acessos). Relógios internos (cancelas entre setores, por exemplo) não devem ter esse campo marcado, pois gerariam registros indevidos para os responsáveis.

Verifique quais relógios representam as entradas e saídas do estabelecimento e confirme que apenas eles estão com saida_empresa = 'S'.

3.3 — Tipos de acesso considerados

A integração processa acessos dos tipos Entrada (E) e Saída (S) — ambos são enviados para a Layers, que os exibe como entrance e exit, respectivamente.

3.4 — Status do acesso

Somente acessos com status_acesso = 1 (sucesso) são considerados. Tentativas negadas ou com erro são ignoradas.

3.5 — Filtro por tipo de pessoa (opcional)

Se a instituição utiliza o Akita Soft para controlar o acesso de diferentes perfis (alunos, funcionários, visitantes), é possível limitar a integração a perfis específicos pelo campo tipo_pessoa da tabela acessos_pessoas. Configure os IDs desejados em api.acessos.filtro.tipoPessoa no arquivo de configuração. Deixar em branco integra todos os perfis.

Layers

3.6 — Cadastrar um identificador no usuário do responsável

Cada responsável deve ter um identificador cadastrado no seu usuário da Layers. Esse campo é necessário para que as notificações de acesso sejam entregues corretamente.

3.7 — Cadastrar os alunos como membros

Cada aluno deve ser cadastrado na Layers como membro com o ID igual ao valor de cod_integracao do Akita Soft. Sem esse vínculo, os acessos do aluno não serão localizados.

3.8 — Associar os responsáveis

Cada responsável deve estar associado ao aluno na Layers com a permissão "Responsável" (guardian). Somente usuários com essa permissão receberão as notificações de acesso do aluno.

Fluxo da integração

A integração opera em dois fluxos independentes: um para consulta de histórico e outro para notificações em tempo real.

Fluxo 1 — Consulta de acessos pelo responsável

Ativado quando o responsável abre a tela de registros de entrada/saída no aplicativo da Layers.

Filtros aplicados na consulta de acessos:

Critério	Valor
`status_acesso`	`1` (sucesso)
`tipo_acesso`	`E` (Entrada) ou `S` (Saída)
`relogios_acessos.saida_empresa`	`S`
`controles_pessoas.cod_integracao`	não nulo
`data_acesso`	últimos `diasRetroativos` dias (padrão: 90, configurável via `api.acessos.filtro.diasRetroativos`)
`tipo_pessoa`	filtrável via config (opcional)

Fluxo 2 — Notificação em tempo real

Ativado automaticamente pelo job agendado. Quando um novo acesso é registrado no Akita Soft, os responsáveis recebem uma notificação push no aplicativo da Layers.