Personalização de API: substituições de pontos de acesso e hooks

Onde encontrá-la

Módulo Administração, tela Importação / Exportação, seção API tweaks, botão API.

A tela é reservada às contas Premium e protegida por uma autenticação reforçada: o Omniscol pede novamente a senha do administrador antes de abrir a janela. Como toda ação nesta tela toca no contrato técnico da sua integração, a sua implantação é feita em articulação com o Omniscol.

Configuração geral

Aqui você define cabeçalhos HTTP (formato chave1:valor1;chave2:valor2) aplicados a todos os hooks. É o lugar natural para carregar um token de autenticação para o seu próprio servidor (por exemplo um Authorization: Bearer … que o seu servidor espera). Para uma substituição, a autenticação vai, ao contrário, nos cabeçalhos próprios ao ponto de acesso (veja abaixo).

Substituição de um ponto de acesso

Uma substituição redefine um ponto de acesso da API do Omniscol para que a aplicação web chame outra URL em seu lugar. Três usos, do mais poderoso ao mais simples.

Servir um dado ao vivo a partir do seu sistema de informação

É o uso mais poderoso. Você redireciona um ponto de acesso em leitura para uma URL externa — tipicamente um ETL que faz a interface com o sistema de informação interno do seu estabelecimento. A aplicação web vai então buscar o dado ao vivo nesse sistema, em vez da cópia local mantida pelo Omniscol.

Concretamente: quando a URL de redirecionamento é um endereço externo absoluto, a aplicação web a chama diretamente, sem passar de novo pelos servidores do Omniscol, e consome a resposta tal como está — exatamente como se ela viesse do Omniscol. A única restrição é que o seu sistema responda no formato esperado pelo Omniscol para esse ponto de acesso (mesma estrutura JSON): não há nenhuma transcodificação intermediária. Para esse ponto de acesso, a cópia local do Omniscol não é mais consultada; o dado exibido é aquele, vivo, do seu sistema.

Exemplo: o catálogo de disciplinas do estabelecimento servido em tempo real a partir do seu sistema de informação, de modo que qualquer atualização do lado da escola fique imediatamente visível no Omniscol, sem reimportação.

A autenticação para o seu sistema vai aqui nos cabeçalhos próprios ao ponto de acesso (por exemplo um Authorization: Bearer …), inseridos na linha da substituição. O método HTTP também pode ser imposto por ponto de acesso.

Religar um ponto de acesso da própria aplicação a uma fonte externa viva é uma possibilidade tão poderosa quanto exigente: deve ser conduzida com o seu departamento de TI, e em articulação com o Omniscol.

Intercalar o seu próprio servidor ou um proxy

Você também pode fazer as chamadas passarem pelo seu próprio servidor ou por um proxy — por exemplo para autorizar o compartilhamento de recursos entre origens (CORS), ou para intercalar uma lógica própria entre a aplicação web e o Omniscol.

Desativar um ponto de acesso

Você desativa um ponto de acesso não lhe atribuindo nenhuma URL de redirecionamento (método null).

Avalie o efeito na interface. O Omniscol é uma aplicação web de página única (SPA) cujos elementos de interface são pilotados pelos pontos de acesso disponíveis: botões, abas e menus só aparecem se o ponto de acesso do qual dependem existir. Desativar um ponto de acesso faz assim desaparecer dinamicamente, na próxima exibição, os elementos de interface que dele dependem — e se você desativar todos os pontos de acesso de um módulo, é o módulo inteiro que desaparece da navegação. Esses elementos são retirados, não apenas ocultados, e tudo se faz sem nenhuma intervenção no código: basta modificar a configuração e recarregar a aplicação.

A tabela lista, por ponto de acesso: a sua chave (o código interno da operação), a sua URL de origem, o método HTTP, a nova URL de redirecionamento e cabeçalhos específicos. Um campo de pesquisa permite encontrar o ponto de acesso a substituir.

Hooks (chamadas de saída)

Um hook pede ao Omniscol para enviar uma requisição HTTP à sua URL depois que uma operação foi bem-sucedida. É o mecanismo para manter um sistema externo informado em tempo real — um painel de exibição, um ambiente virtual de aprendizagem, um sistema de recursos humanos, uma sincronização própria…

Um hook liga-se de duas maneiras:

• a um ponto de acesso preciso (a chave da operação);
• a um evento agrupado, que cobre de uma vez uma família de operações. Existem três eventos agrupados:
  • alteração de horário (criação, deslocamento ou exclusão de aulas, ativação de um horário, e ausências de professor ou de turma assim que uma data é tocada);
  • alteração de um professor (adição, atualização ou exclusão);
  • alteração de uma disciplina (disciplinas personalizadas).

Para cada hook, você preenche a URL de retorno, o método HTTP, a caixa « com dados » (é preciso anexar o corpo da requisição de origem?) e cabeçalhos próprios.

O que o seu servidor recebe

A chamada é enviada em application/json e carrega, além dos seus cabeçalhos:

• o corpo da requisição de origem se a opção « com dados » estiver ativada;
• um bloco de metadados Omniscol: a URL chamada, o código do ponto de acesso, o método, os parâmetros, o token de autenticação do usuário e o identificador do estabelecimento;
• cabeçalhos de rastreabilidade: X-OS-original-query, X-OS-original-endpoint, X-OS-auth e X-School.

Para o evento alteração de horário, quando a opção « com dados » está ativa, a chamada inclui ainda um diferencial das aulas (aulas adicionadas, alteradas, excluídas) — prático para propagar apenas o que mudou.

Comportamento

Os hooks partem em segundo plano, depois que a operação do usuário chegou a bom termo: eles não deixam a interface mais lenta e não a bloqueiam em caso de falha do seu servidor. Uma chamada de saída que não chega a bom termo é registrada em log, sem interromper o trabalho no Omniscol. Cada chamada tem um tempo-limite curto (alguns segundos): o seu servidor deve confirmar o recebimento rápido e tratar o restante do seu lado.

Bom saber

• A API do Omniscol expõe um subconjunto de operações; uma substituição ou um hook só se aplica aos pontos de acesso realmente expostos. Veja API Omniscol para a lista e a autenticação.
• Para uma integração com um pacote de software (ERP, SIRH, ambiente virtual de aprendizagem), a sincronização dedicada é muitas vezes mais adequada — veja Sincronização com sistemas externos. Internamente, o mesmo sistema de hook é utilizado.
• Para que um agente IA consulte os seus dados sem desenvolvimento, veja MCP — conectar um agente IA externo.