Публічний API і MCP: що можна читати й змінювати ззовні

OneB Staff можна під'єднати до інших систем і до ШІ-асистентів. Для цього є дві поверхні: API для інтеграцій (для розробників, які пишуть код) і MCP для ШІ-асистентів (Claude, ChatGPT та інші, які вміють працювати з інструментами). Обидві вмикаються в Налаштуваннях, пункт «Експериментальні функції».

Екран «Експериментальні функції»: перемикачі MCP і API, рівень доступу, ключі

Що можна робити ззовні

Через API і MCP доступне все те саме, що бачить і робить користувач у застосунку, але поступово: спочатку читання, далі зміни по розділах.

Читання (доступне всім): команда (особи, трудові договори, посади), довідники (компанії, відділи, посади, календарі, категорії нарахувань, змінні, схеми), нарахування й виплати, баланси «кому скільки винні», відсутності й залишки відпусток, прогони нарахувань, платіжна відомість і прогноз ФОТ, а також попередні перегляди «що буде, якщо» (нарахування за період, перерахунок, компенсація відпустки) без жодних змін у даних.

Зміни (перший етап — команда й довідники):

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

Зміни (другий етап — історія, відсутності, значення):

Імпорт історії зі старої системи або таблиці: працівники, історія окладів, нарахування, виплати й відсутності. Докладніше — у розділі нижче.
Відсутності: створити документ (відпустка, лікарняний, відрядження тощо), змінити його, поки він не проведений, підтвердити або зняти підтвердження, змінити дату завершення вже проведеної відсутності з перерахунком, провести нарахування по одному документу або пакетом до 100.
Типи відсутностей і норми добових: подивитися картку, створити новий тип чи норму, відредагувати. Ключ типу (alias) не можна змінити, якщо тип уже використаний у документах; ключ норми утворюється з назви при створенні й далі не змінюється.
Компенсація невикористаної відпустки: провести для звільненого працівника на вказану дату. Якщо невикористаних днів не лишилося, система відмовить і пояснить чому.
Значення змінних розрахунку: задати постійні значення (оклад, ставки) на рівні всього робочого простору, компанії, відділу, посади з довідника або конкретної посади працівника; додати версію значення «з дати»; задати помісячні показники (наприклад, відпрацьовані години) працівникам компанії за місяць.

Третій етап додасть прогони нарахувань, ручні нарахування й виплати, перерахунки; четвертий — сторно, видалення й керування каталогом змінних і схем.

Імпорт історії через API або ШІ-асистента

Імпорт двокроковий, щоб помилкові дані не потрапили в облік непомітно:

Подати рядки. Інтеграція або асистент надсилає список рядків одного типу (до 1000 за раз). Система нічого не записує, а повертає результат перевірки: скільки рядків готові, скільки з попередженнями, скільки з помилками, і перші 20 помилок із номерами рядків і порадою, що виправити.
Підтвердити. Якщо все гаразд, підтвердження записує дані. Помилкові рядки можна пропустити, підтвердивши лише готові. Непідтверджений результат перевірки зберігається 7 днів, потім видаляється.

Рекомендований порядок для перенесення історії клієнта: спочатку працівники (вони створюються разом із першим трудовим договором; невідомі відділи й посади додаються в довідник автоматично), далі історія окладів, нарахування, виплати й відсутності. Дати й суми можна подавати у звичному людському вигляді («05.07.2026», «19 250,50») — система їх розпізнає. Імпорт працівників займає місця ліміту працівників тарифу: якщо ліміт вичерпано, підтвердження відмовить, а результат перевірки залишиться, щоб повторити після зміни тарифу.

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

Рівні доступу

Що саме дозволено, визначає рівень:

Рівень	Що дозволяє
Читання	лише дивитися дані
Читання і зміни	створювати, редагувати, звільняти, проводити, імпортувати
Повний	те саме, а також видаляти й скасовувати

Для API рівень має кожен ключ окремо, для MCP один рівень задається на весь робочий простір. Якщо ШІ-асистент або інтеграція намагається зробити більше, ніж дозволено, у відповіді буде зрозуміле пояснення, який рівень потрібен і де його увімкнути.

Захист від втрати історії

Видалити через API чи MCP можна лише те, що не має історії:

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

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

Окремо про значення змінних: зняття значення на якомусь рівні видаляє всю історію версій цієї змінної на цьому рівні (включно з майбутніми). Якщо потрібно лише змінити суму — задайте нове значення або додайте версію «з дати», а не знімайте його.

Як почати

Відкрийте Налаштування → Експериментальні функції.
Для ШІ-асистента: увімкніть «Дозволити підключення через MCP», оберіть рівень доступу й скопіюйте адресу підключення в налаштування асистента.
Для інтеграції кодом: увімкніть «Дозволити доступ через API», натисніть «Створити ключ», задайте назву, рівень і за потреби термін дії. Ключ показується один раз, збережіть його одразу. Опис усіх операцій є за посиланням «Документація API».
Ключ, що більше не потрібен, відкличте в тому самому списку.

Доступ через API і MCP залежить від тарифу робочого простору.