O FlexiProject disponibiliza uma API REST através da qual outro sistema pode ler e alterar os dados da organização — alimentar um relatório de BI, sincronizar projetos com um ERP ou automatizar uma tarefa repetitiva. A descrição completa dos endpoints encontra-se em developers.flexi-project.com.
Para chamar a API precisa de um token de acesso pessoal (token de API). Cria-o no seu perfil, no separador API, e ele funciona com as suas permissões: a API mostra exatamente os dados que vê na aplicação e nada mais.
Token de acesso pessoal
Quem pode criar um token
Um token é criado, para a sua própria conta, por um utilizador com licença Completa (ver Licenças) e por um administrador do sistema; o separador API só é visível para eles. Não é necessária nenhuma permissão de administrador. O token tem as permissões do seu proprietário, pelo que chega aos mesmos projetos e campos que o proprietário vê na aplicação. Duas pessoas com funções diferentes obtêm resultados diferentes com o mesmo pedido.
Um token deixa de funcionar quando a conta é desativada, removida da organização ou bloqueada, pelo que não é preciso eliminar tokens quando alguém sai da organização.
Criar um token
- Abra o menu do avatar, escolha Perfil do utilizador e aceda ao separador API (ver Perfil do utilizador).
- Clique em Novo token.
- Introduza um Nome — até 100 caracteres. O nome deve indicar a que integração o token se destina, porque é a única forma de distinguir os seus tokens mais tarde.
- Defina a Data de validade. A mais próxima é amanhã, a mais distante daqui a 365 dias, e o campo abre com 30 dias. O token expira no fim do dia escolhido.
- Clique em Criar token.
Copie o token de imediato
A janela O token de acesso pessoal foi criado mostra o valor completo apenas uma vez, com um aviso: Copie o token e guarde-o num local seguro — depois de fechar esta janela, não será possível voltar a consultá-lo. O botão Copiar copia o valor para a área de transferência; cole-o logo no sistema que o vai utilizar. Depois de fechar a janela, ninguém consegue recuperar o valor — nem o próprio utilizador, nem um administrador, nem o suporte. Se perder um token, elimine-o e crie um novo.
Lista de tokens
O separador API lista os seus tokens nas colunas Nome, Token, Criado em e Expira em. A coluna Token mostra apenas os primeiros caracteres do valor — o suficiente para identificar o token que está guardado numa integração.
A coluna Expira em avisa com antecedência: um token que expira nos próximos sete dias tem uma etiqueta com o número de dias que faltam, um que expira hoje mostra expira hoje e um expirado mostra expirou. Um token expirado permanece na lista até o eliminar, mas já não autentica nada.
Pode ter até dez tokens ativos em simultâneo. Quando o limite é atingido, a aplicação recusa criar mais um, com a mensagem Já tem 10 tokens de acesso pessoal ativos. Elimine um token não utilizado para criar um novo. Os tokens expirados não contam para o limite.
Eliminar um token
O ícone do caixote do lixo na linha de um token elimina-o após confirmação. A aplicação avisa que as integrações que o utilizam deixarão de funcionar imediatamente — e deixam, no pedido seguinte. A eliminação não pode ser anulada; substituir um token significa sempre criar um novo token com um novo valor.
Utilizar um token
O token de API não é enviado em cada pedido. Troca-se uma vez por um token de acesso e, a partir daí, utiliza-se esse token de acesso.
Envie um POST para /api/user/token/personal com o seu endereço de e-mail e o valor do token:
POST /api/user/token/personal
Content-Type: application/json
{ "email": "anna.kowalska@example.com", "token": "fpat_…" }A resposta contém o access_token, o respetivo tipo, o identificador da organização à qual o token pertence e o número de segundos durante os quais é válido. Envie o token de acesso no cabeçalho Authorization das chamadas seguintes e repita a troca quando este expirar.
O endereço de e-mail tem de pertencer à conta que criou o token, e é o próprio token que determina a que organização tem acesso — se trabalha em mais do que uma, crie um token separado em cada uma.
As tentativas falhadas repetidas são limitadas: após dez tentativas falhadas para o mesmo endereço de e-mail, as seguintes são rejeitadas durante quinze minutos. Se uma integração começar de repente a receber recusas em massa, verifique o valor guardado em vez de repetir o pedido em ciclo.
A troca de um token de API também funciona quando o início de sessão com palavra-passe está desativado, porque não é uma pessoa que está a iniciar sessão (ver Métodos de início de sessão).
