OAuth-додатки для партнерів

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

Якщо інтеграція призначена лише для одного акаунта, простіше створити застосунок, що належить акаунту.

Створення застосунку

Відкрийте акаунт партнера.
Перейдіть до розділу OAuth-застосунки.
Виберіть Створити застосунок.
Укажіть назву й опис, які бачитимуть користувачі та адміністратори.
Виберіть тип OAuth-клієнта.
Додайте URI перенаправлення.
Виберіть мінімально необхідні області доступу REST API.
Збережіть застосунок і скопіюйте його облікові дані.

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

Тип OAuth-клієнта

Тип	Призначені застосунки	Облікові дані
Публічний	Мобільні, настільні та браузерні застосунки, а також локальні MCP-клієнти.	Лише `client_id`. Секрету клієнта немає; PKCE S256 обов’язковий.
Конфіденційний	Серверні застосунки, у яких секрет можна зберігати поза пристроєм користувача та клієнтським кодом.	`client_id` і `client_secret`.

Тип OAuth-клієнта не залежить від того, чи опубліковано застосунок. Наприклад, приватний мобільний застосунок є публічним OAuth-клієнтом без секрету.

URI перенаправлення

Укажіть кожну URL-адресу, на яку Planfix може повернути користувача після входу.

Для вебсервісу використовуйте https.
http дозволено лише для адрес із зворотним зв’язком, як-от localhost і 127.0.0.1.
Клієнт може використовувати динамічний порт для адреси із зворотним зв’язком, але схема, хост, шлях і параметри запиту мають збігатися.
Не використовуйте підстановочні символи, фрагменти URL або URI перенаправлення, які вам не належать.

Області доступу

Області доступу визначають максимальний набір дозволів застосунку. Запитуйте лише необхідні рівні доступу зі списку областей доступу REST API.

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

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

Підключення акаунта клієнта

Приватний OAuth-застосунок, що належить партнеру, має бути явно схвалений адміністратором у кожному акаунті.

Відкрийте застосунок в акаунті партнера.
У полі для посилання на схвалення введіть назву акаунта клієнта.
Скопіюйте згенероване посилання та надішліть його адміністратору цього акаунта.
Попросіть адміністратора перевірити власника, URI перенаправлення та області доступу, а потім схвалити застосунок.
Після схвалення користувачі акаунта зможуть завершити OAuth-авторизацію. Кожен користувач окремо надає згоду від свого імені.

Посилання відкриває розділ Керування акаунтом → API → OAuth- і MCP-застосунки та показує запитуваний застосунок.

Адміністратор, який також підключає застосунок, може вибрати Схвалити й підключити.

Приватні й опубліковані застосунки

Статус	Як застосунок допускається до акаунта
Приватний	Завжди потребує явного схвалення адміністратора кожного акаунта.
Опублікований	Доступний без окремого схвалення, якщо в політиці акаунта вибрано Дозволити опубліковані застосунки. Якщо вибрано Лише схвалені застосунки, схвалення все одно потрібне.

Публікація потребує окремої перевірки Planfix. Перед поданням застосунку підготуйте зрозумілі назву й опис, мінімальний набір областей доступу, робочі URI перенаправлення та документацію для користувачів про підключення й видалення інтеграції. Щоб дізнатися про процедуру публікації, зверніться до служби підтримки Planfix.

Адреси підключення

Використовуйте глобальні кінцеві точки OAuth:

Призначення	Адреса
Авторизація	`https://auth.planfix.com/oauth/authorize`
Токен	`https://auth.planfix.com/oauth/token`
Інформація про користувача	`https://auth.planfix.com/oauth/userinfo`
MCP	`https://mcp.planfix.com/mcp`

Не додавайте назву акаунта до глобальної URL-адреси. Користувач вибирає акаунт на сторінці Planfix. Повний опис протоколу, зокрема resource, PKCE, оновлення та відкликання токенів, наведено в OAuth 2.0 для додатків.

Керування застосунком

Партнер може:

змінювати назву й опис;
змінювати URI перенаправлення та області доступу;
вимикати й знову вмикати застосунок;
змінювати секрет клієнта конфіденційного застосунку;
створювати посилання на схвалення застосунку для конкретного акаунта.

Після зміни секрету клієнта старий секрет одразу перестає працювати. Оновіть секрет на сервері інтеграції та ніколи не надсилайте його користувачам.

Якщо вимкнути застосунок, OAuth-авторизація буде заблокована, а видані ним токени — недійсні в усіх акаунтах. Ця дія впливає на всіх клієнтів, які використовують застосунок.