API i token API

FlexiProject udostępnia API REST, przez które inny system może odczytywać i zmieniać dane organizacji — zasilać raport BI, synchronizować projekty z ERP albo automatyzować powtarzalną czynność. Pełny opis punktów końcowych jest na developers.flexi-project.com.

Do wywołania API potrzebny jest osobisty token dostępu (token API). Użytkownik tworzy go samodzielnie w profilu, na zakładce API, a token działa z uprawnieniami tego użytkownika: API pokazuje dokładnie te dane, które użytkownik widzi w aplikacji, i nic ponad to.

Osobisty token dostępu

Kto może utworzyć token

Token tworzy dla własnego konta użytkownik z licencją Pełna (zobacz Licencje) oraz administrator systemu; zakładka API jest widoczna tylko dla nich. Nie potrzeba uprawnień administratora. Token niesie uprawnienia właściciela, więc sięga po te same projekty i pola, które widzi on w aplikacji. Dwie osoby o różnych rolach dostają z tego samego zapytania różne wyniki.

Token przestaje działać, gdy konto zostanie dezaktywowane, usunięte z organizacji albo zablokowane, więc po odejściu pracownika nie trzeba sprzątać jego tokenów.

Tworzenie tokenu

1. Należy otworzyć menu awatara, wybrać Profil użytkownika i przejść do zakładki API (zobacz Profil użytkownika). Wyświetli się lista tokenów.
2. Po kliknięciu przycisku Nowy token otworzy się okno tworzenia tokenu.
3. Należy wpisać Nazwę — do 100 znaków. Nazwa powinna mówić, jakiej integracji służy token, bo tylko po niej można później odróżnić tokeny.
4. Następnie należy ustawić Datę ważności. Najwcześniejsza jest jutrzejsza, najpóźniejsza — za 365 dni, a pole otwiera się na 30 dniach. Token wygasa z końcem wybranego dnia.
5. Po kliknięciu przycisku Utwórz token zostanie utworzony token i pojawi się okno z jego wartością.

Skopiowanie tokenu od razu

Okno Osobisty token dostępu został utworzony pokazuje pełną wartość tylko raz, z ostrzeżeniem: Skopiuj token i przechowaj go w bezpiecznym miejscu — po zamknięciu tego okna nie będzie już możliwości jego odczytania. Przycisk Kopiuj kopiuje wartość do schowka, skąd wkleja się ją wprost do systemu, który będzie z niej korzystał. Po zamknięciu okna wartości nie odzyska nikt — ani użytkownik, ani administrator, ani wsparcie. Zgubiony token trzeba usunąć i utworzyć od nowa.

Lista tokenów

Zakładka API wypisuje tokeny użytkownika w kolumnach Nazwa, Token, Utworzono i Wygasa. Kolumna Token pokazuje tylko początkowe znaki wartości, tyle, by dopasować token do zapisanego w integracji.

Kolumna Wygasa ostrzega z wyprzedzeniem: token wygasający w ciągu siedmiu dni ma znacznik z liczbą pozostałych dni, wygasający dziś — wygasa dziś, a przeterminowany — wygasł. Token po terminie zostaje na liście do usunięcia, ale niczego już nie uwierzytelnia.

Jednocześnie można mieć do dziesięciu aktywnych tokenów. Po osiągnięciu limitu aplikacja odmawia utworzenia kolejnego, z komunikatem Masz już 10 aktywnych osobistych tokenów dostępu. Usuń nieużywany token, aby utworzyć nowy. Tokeny wygasłe nie wliczają się do limitu.

Usuwanie tokenu

Aby usunąć token, należy kliknąć ikonę kosza w wierszu tokenu i potwierdzić. Token zostanie usunięty. Aplikacja ostrzega, że integracje, które go używają, przestaną działać natychmiast — i przestają przy najbliższym żądaniu. Usunięcia nie można cofnąć; token zastępuje się zawsze nowym tokenem o nowej wartości.

Używanie tokenu

Tokenu API nie wysyła się przy każdym żądaniu. Wymienia się go raz na token dostępowy i dalej posługuje tym tokenem dostępowym.

POST na adres /api/user/token/personal z adresem e-mail i wartością tokenu:

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

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

Odpowiedź zawiera access_token, jego typ, identyfikator organizacji, do której należy token, oraz liczbę sekund jego ważności. Token dostępowy wysyła się w nagłówku Authorization kolejnych wywołań, a po jego wygaśnięciu wymianę trzeba powtórzyć.

Adres e-mail musi należeć do konta, które utworzyło token, a o organizacji decyduje sam token — przy pracy w więcej niż jednej organizacji tworzy się osobny token w każdej z nich.

Powtarzane nieudane próby są ograniczane: po dziesięciu nieudanych próbach dla tego samego adresu e-mail kolejne są odrzucane przez piętnaście minut. Gdy integracja zaczyna masowo dostawać odmowy, trzeba sprawdzić zapisaną wartość, zamiast ponawiać żądanie w pętli.

Wymiana tokenu API działa także przy wyłączonym logowaniu hasłem, bo nie jest logowaniem człowieka (zobacz Metody logowania).