Como o Omniscol funciona — uma única API, uma única fonte de verdade

Alguns pontos sobre como o Omniscol é construído merecem ser conhecidos antes de integrá-lo: explicam por que a API é tão completa, como a interface se adapta a cada usuário e um ponto de confidencialidade a ter em mente.

Uma única aplicação sobre uma única API

O Omniscol é executado como uma única aplicação web no seu navegador. Cada tela, botão e tabela é desenhado chamando a API pública do Omniscol — a mesma API que você pode chamar — documentada na referência de API interativa do Omniscol, a página Desenvolvedores (omniscol.com/pt/developers). Não existe uma API oculta, «real», por trás daquela que você integra: o que a interface usa é o que você obtém. Algumas operações vão no sentido contrário — oferecidas para a integração, mas não utilizadas pela própria aplicação —: por exemplo, os pontos de acesso de busca avançada e resolução de entidade (destinados a um agente de IA via MCP), ou aqueles que permitem a um sistema externo alimentar o Omniscol (um ETL que mantém um banco de dados externo sincronizado).

operationId — uma chave, uma única fonte de verdade

Cada operação é um par método + URL (por exemplo GET /api/schedules/lessons/{datesrange}), e cada uma carrega um identificador estável: seu operationId (aqui os_schedules_dates_get). O nome é estruturado: os (Omniscol), depois o módulo (schedules), depois aquilo sobre o que a operação atua (dates — às vezes vários segmentos unidos por hífens) e sempre o método HTTP por último (get, post, put, delete). É essa chave única que o Omniscol usa em toda parte — para nomear a operação na página Desenvolvedores, para construir a ferramenta MCP correspondente e para designá-la a partir de uma personalização de API ou desta ajuda. Definida uma única vez, ela mantém todas as superfícies sincronizadas: a documentação, as ferramentas e a interface não podem divergir, pois todas leem a mesma definição.

A interface segue os seus direitos

Um elemento gráfico dotado de uma ação — um botão, uma aba, uma entrada de menu — só aparece quando a operação que o sustenta lhe é acessível. Isso depende do seu papel e dos seus papéis personalizados (veja Usuários e papéis), do seu plano e das suas opções (veja Planos e opções do Omniscol). Altere um desses elementos e a interface se recompõe: elementos, e até módulos inteiros, aparecem ou desaparecem em consequência.

O mesmo princípio atua além dos seus direitos pessoais. O departamento de TI pode desativar certas operações por meio de uma personalização de API, e os elementos correspondentes desaparecem da interface (veja Personalização de API). O mesmo vale quando um dado é mantido atualizado por uma sincronização externa: sua criação e sua modificação locais podem ser desativadas, e seus controles cedem então lugar à sincronização (veja Sincronização com sistemas externos).

É por isso que o Omniscol não tem nenhum portal separado para alunos ou professores. Há uma única aplicação; cada pessoa vê a interface sincronizada com os seus próprios direitos — um aluno, um professor, um administrador e o titular de um papel personalizado obtêm exatamente as operações a que têm direito, e nada mais.

A interface é uma comodidade, não a tranca

Como a interface é guiada pelos seus direitos, seria tentador ver um botão oculto como uma fronteira de segurança. Não é. Cada chamada é reverificada no servidor em relação à sua identidade e aos seus direitos; uma operação a que você não tem direito é recusada ali, mostre o que mostrar a interface. A interface se adapta por clareza e comodidade; a fronteira real é aplicada no servidor, a cada requisição.

Tokens e links de compartilhamento, o mesmo modelo

Um token de API ou um link de compartilhamento é restrito a um conjunto de operações: as que você autoriza ao criá-lo. O servidor aplica essa restrição a cada chamada, exatamente como para um usuário conectado. Um link de compartilhamento, um token e uma pessoa na interface são três formas de alcançar a mesma API controlada pelos direitos — nunca uma porta dos fundos que a contorna.

Atravessar uma queda de conexão

Como cada tela lê a API, o Omniscol também pode conservar no seu navegador as respostas já recebidas, para que uma breve perda de rede não interrompa a sua leitura. Essa cópia local vive no seu banco de dados (IndexedDB), ao lado do cache de páginas comum do navegador. É um cache de leitura: se a conexão cair, você continua vendo o que já havia aberto. Ela não coloca as suas modificações em fila nem as reproduz — uma modificação sempre passa pelo servidor.

Essa cópia local se baseia no seu consentimento. Na primeira vez em um navegador, o Omniscol pergunta se você confia nele; a cópia começa depois que você aceitou. A entrada Cache offline do menu do usuário a ativa ou a apaga depois a qualquer momento — uma marca de seleção indica que ela está ativa.

Duas coisas que convém saber:

• Os dados pessoais são excluídos. Somente as leituras bem-sucedidas são conservadas; as respostas que o servidor marca como não armazenáveis (dados de sessão e de autenticação) nunca são colocadas em cache, e do que é colocado em cache o software retira os dados de contato das pessoas — e-mail, telefone, data de nascimento, login, número de identificação, status da senha — e remove por completo as contas de administrador. A cópia local contém os dados de trabalho comuns, não o cadastro nominal.
• Em um computador compartilhado, prefira uma janela de navegação privada (anônima). Sair da conta não apaga essa cópia local (nem o cache normal do navegador); uma janela privada descarta ambos ao ser fechada. É o cuidado que qualquer aplicação web merece em uma máquina que você não controla.