Notificações e endpoints públicos do OpenPlatform

Além do lançamento e da verificação, o OpenPlatform tem alguns endpoints para as aplicações e para outros sistemas. Estão em controllers/verify.js, controllers/api.js e controllers/socket.js.

Enviar uma notificação

A resposta da verificação contém notify, um endereço da forma <platform url>/notify/?token=<checksum of user and application>, quando o utilizador aceita notificações. A aplicação envia-lhe um POST com o cabeçalho x-token e um corpo JSON:

Campo	Significado
body	o texto da notificação
path	o caminho dentro da aplicação que a notificação abre
icon, color	opcionais: substituem o ícone e a cor da aplicação

O valor de x-token é o token de notificação que o OpenPlatform deriva para esse utilizador e aplicação: o MD5 do endereço de notificação com o sal do reqtoken da aplicação, e o MD5 desse resultado com o sal do seu restoken (FUNC.makenotify em definitions/func.js). Ambos os segredos são os mesmos que a aplicação partilha para o lançamento (registar uma app).

O OpenPlatform responde Invalid token quando a soma de verificação ou o cabeçalho não coincidem, e Not allowed notifications quando o utilizador ou a aplicação não as aceita. Verifica também os endereços permitidos da aplicação e que o utilizador está confirmado, ativado e ativo. Quando tudo está certo:

1. guarda a notificação (tabela tbl_notification) e aumenta o contador de não lidas do utilizador;
2. atualiza as sessões desse utilizador abertas no portal, para que o contador apareça logo;
3. publica Notifications.create por TMS quando a definição $tms está ativa;
4. devolve o identificador da notificação.

Para os utilizadores que estão offline e têm notificações por ler, uma tarefa de serviço envia um resumo por e-mail ("Unread notifications") quando as definições de correio estão configuradas, no máximo uma vez a cada três dias por utilizador (definitions/init.js).

A API de utilizadores (um token)

GET /users/ devolve os grupos e os utilizadores da plataforma como JSON. Está desativada até as definições allow_token e token serem definidas. O chamador envia o token como o parâmetro de consulta token ou como o cabeçalho x-token; as tentativas erradas repetidas são bloqueadas. Os utilizadores vêm sem segredos: identificador, referência, idioma, género, foto (um endereço absoluto), nome, e-mail, cor, preferências, indicadores (sa, isdisabled, isinactive, isonline), datas e os ids dos seus grupos.

Carregar uma imagem

POST /upload/base64/ (até 2 MB) aceita um corpo JSON com o nome do ficheiro e file como data URI, e apenas JPEG. Precisa de um utilizador com sessão iniciada ou do token de consulta da definição servicetoken (veja definições e base de dados para saber de onde vem essa chave). A imagem é guardada no armazenamento de ficheiros files e a resposta é o seu endereço, /files/<id and checksum>.jpg; o endereço só funciona com a soma de verificação.

Várias instâncias: o socket de sincronização

SOCKET /sync/ liga instâncias do OpenPlatform. Um cliente é aceite quando a definição sync está ativa e o token da consulta é igual a sync_token; qualquer outro cliente é fechado com o código 4001 meio segundo depois de abrir. As mensagens de um cliente confirmado são retransmitidas aos outros e, enquanto um cliente confirmado se está a religar, as mensagens ficam em fila até dez segundos.