# Notificações e endpoints públicos do OpenPlatform

> Envie uma notificação a um utilizador a partir da sua aplicação e use a API com token para a lista de utilizadores, o carregamento de imagens e o socket de sincronização de várias instâncias.

Framework: openplatform
Product: OpenPlatform (openplatform@5)
Language: pt
Content-SHA256: 188a062f65aaa5a2ee91205b560a707cdc650e5de100f59aa6da4b5cbcfe03a7
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

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](/en/openplatform/register-an-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](/en/openplatform/settings-and-database/) 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.