API та API-токен

FlexiProject надає REST API, через який інша система може читати й змінювати дані організації — наповнювати звіт BI, синхронізувати проєкти з ERP або автоматизувати повторювану роботу. Повний опис кінцевих точок міститься на developers.flexi-project.com.

Щоб викликати API, потрібен персональний токен доступу (токен API). Ви створюєте його самі у своєму профілі, на вкладці API, і він працює з вашими правами: API показує рівно ті дані, які ви бачите в застосунку, і нічого більше.

Персональний токен доступу

Хто може створити токен

Токен створює для власного облікового запису користувач із ліцензією Повна (див. Ліцензії) і системний адміністратор; вкладка API видима лише для них. Права адміністратора не потрібні. Токен має права свого власника, тому дає доступ до тих самих проєктів і полів, які власник бачить у застосунку. Дві особи з різними ролями отримають різні результати на той самий запит.

Токен перестає працювати, коли обліковий запис деактивовано, видалено з організації або заблоковано, тож видаляти токени, коли хтось залишає організацію, не потрібно.

Створення токена

1. Відкрийте меню аватара, виберіть Профіль користувача і перейдіть на вкладку API (див. Профіль користувача).
2. Натисніть Новий токен.
3. У полі Назва введіть назву — до 100 символів. Назва має вказувати, якій інтеграції служить токен, бо це єдиний спосіб відрізнити свої токени згодом.
4. Задайте Термін дії. Найраніший — завтра, найпізніший — через 365 днів від сьогодні, а поле відкривається зі значенням 30 днів. Токен закінчується наприкінці вибраного дня.
5. Натисніть Створити токен.

Скопіюйте токен одразу

Вікно Персональний токен доступу створено показує повне значення лише один раз, із попередженням: Скопіюйте токен і збережіть його в безпечному місці — після закриття цього вікна його більше не можна буде переглянути. Кнопка Копіювати копіює значення в буфер обміну; вставте його одразу в систему, яка його використовуватиме. Після закриття вікна ніхто не може відновити значення — ні ви, ні адміністратор, ні підтримка. Якщо ви втратили токен, видаліть його й створіть новий.

Список токенів

Вкладка API показує ваші токени в стовпцях Назва, Токен, Створено і Дійсний до. Стовпець Токен показує лише перші символи значення — достатньо, щоб зіставити токен із тим, що збережено в інтеграції.

Стовпець Дійсний до попереджає заздалегідь: токен, що закінчується протягом семи днів, має позначку з кількістю днів, що залишилися; той, що закінчується сьогодні, показує закінчується сьогодні, а прострочений — термін дії минув. Прострочений токен залишається у списку, доки ви його не видалите, але нічого більше не автентифікує.

Одночасно можна мати не більше десяти активних токенів. Після досягнення ліміту застосунок відмовляє у створенні ще одного й показує повідомлення У вас уже є 10 активних персональних токенів доступу. Видаліть невикористовуваний токен, щоб створити новий. Прострочені токени до ліміту не зараховуються.

Видалення токена

Іконка кошика в рядку токена видаляє його після підтвердження. Застосунок попереджає, що інтеграції, які його використовують, негайно перестануть працювати — і вони справді перестають, під час наступного запиту. Видалення не можна скасувати; замінити токен означає завжди створити новий токен з новим значенням.

Використання токена

Токен API не надсилається з кожним запитом. Ви один раз обмінюєте його на токен доступу й далі користуєтеся цим токеном доступу.

Надішліть запит POST на /api/user/token/personal зі своєю адресою електронної пошти та значенням токена:

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

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

Відповідь містить access_token, його тип, ідентифікатор організації, до якої належить токен, і кількість секунд, протягом яких він дійсний. Надсилайте токен доступу в заголовку Authorization наступних викликів і повторіть обмін, коли він закінчиться.

Адреса електронної пошти має належати обліковому запису, який створив токен, а в яку організацію ви потрапите, визначає сам токен — якщо ви працюєте в кількох, створіть окремий токен у кожній.

Повторні невдалі спроби обмежено: після десяти невдалих спроб для тієї самої адреси електронної пошти наступні відхиляються протягом п’ятнадцяти хвилин. Якщо інтеграція раптом починає масово отримувати відмови, перевірте збережене значення, а не повторюйте запит у циклі.

Обмін токена API працює й тоді, коли вхід із паролем вимкнено, бо в систему входить не людина (див. Способи входу).