API e token de API

O FlexiProject disponibiliza uma API REST através da qual outro sistema pode ler e alterar os dados da organização. Isto permite 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 token no seu perfil, no separador API.

O token funciona com as permissões do seu proprietário. A API devolve exatamente os dados que o proprietário vê na aplicação e nada mais. Duas pessoas com funções diferentes obtêm, por isso, resultados diferentes com o mesmo pedido.

Token de acesso pessoal

Quem pode criar um token

Um token para a sua própria conta é criado por um utilizador com licença Completa (ver Licenças). O separador API só é visível para esses utilizadores.

Importante: a troca de um token por um token de acesso falha quando a conta é desativada, removida da organização ou bloqueada, ou quando o utilizador deixa de ter licença Completa.

Criar um token

Avatar menu with User profile and the API tab in the user profile

  1. Abra o menu do avatar (ícone de avatar no canto superior direito do ecrã), escolha Perfil do utilizador e aceda ao separador API (ver Separador Informações). É apresentada a lista de tokens.
  2. Clique em Novo token. Abre-se a janela Novo token de acesso pessoal.
  3. No campo Nome, 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 tokens mais tarde.
  4. No campo Data de validade, defina uma data. O token expira no fim do dia escolhido.
  5. Clique em Criar token. O FlexiProject cria o token e apresenta uma janela com o respetivo valor.

O intervalo de datas do campo Data de validade é:

  • A data mais próxima é amanhã.
  • A data mais distante é daqui a 365 dias.
  • Por predefinição, estão definidos 30 dias.

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.

Atenção: depois de fechar a janela, ninguém consegue recuperar o valor: nem o utilizador, nem um administrador, nem o suporte. Um token perdido tem de ser eliminado e criado de novo.

Lista de tokens

API tab in the user profile listing two personal access tokens

O separador API lista os tokens do utilizador 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 mostra avisos com antecedência:

  • Um token que expira nos próximos sete dias tem uma etiqueta com o número de dias que faltam.
  • Um token que expira hoje tem a etiqueta expira hoje.
  • Um token expirado tem a etiqueta expirou.

Um token expirado permanece na lista até o eliminar, mas já não autentica nada.

Importante: pode ter até dez tokens ativos em simultâneo. Os tokens expirados não contam para o limite.

Depois de atingido o limite, o botão Novo token fica inativo, e a dica indica: Já tem 10 tokens de acesso pessoal ativos. Elimine um token não utilizado para criar um novo.

Eliminar um token

Para eliminar um token, clique no ícone do caixote do lixo na respetiva linha (visível ao apontar para a linha) e confirme. O FlexiProject elimina o token.

Atenção: a eliminação não pode ser anulada. Um token eliminado já não pode ser trocado por um token de acesso, e a integração tem de obter um novo token com um novo valor. Um token de acesso emitido anteriormente funciona até ao fim da sua validade (60 minutos).

Utilizar um token

Importante: 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.

Para trocar o token, envie um POST para /api/users/token/personal com o endereço de e-mail e o valor do token:

POST /api/users/token/personal
Content-Type: application/json

{ "email": "anna.kowalska@example.com", "token": "fpat_…" }

A resposta contém o access_token, o respetivo tipo (token_type), o identificador da organização à qual o token pertence (selectedTenantId) e o tempo de validade do token de acesso, em minutos (expires).

Envie o token de acesso no cabeçalho Authorization das chamadas seguintes. Quando expirar, repita a troca.

O endereço de e-mail tem de pertencer à conta que criou o token. O próprio token determina a que organização tem acesso, pelo que, se trabalha em mais do que uma organização, precisa de 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).