Публічне API та API-ключі OneB Finance

Якщо у вас є власний сайт, CRM, облікова система чи скрипт, який збирає дані з кількох сервісів, їх можна зʼєднати з OneB Finance через публічне API. Так платежі з вашої системи потраплятимуть у Finance без ручного імпорту, а довідники контрагентів і статей можна тримати узгодженими автоматично. Для доступу потрібен API-ключ, який ви створюєте самі в застосунку і передаєте розробникові.

Де це в застосунку: Налаштування → API-ключі. Пункт бачить лише адміністратор робочого простору.

Кому це потрібно

Стаття для тих, хто працює з розробником або технічним партнером: ключ створюєте ви, а використовує його ваша система. Якщо вам достатньо готових інтеграцій — синхронізації з банками, імпорту виписок чи звʼязки з OneB Invoice — API не знадобиться.

Як створити API-ключ

Відкрийте Налаштування → API-ключі і натисніть «Створити ключ».
Вкажіть назву ключа (наприклад, «Інтеграція з CRM») і, за бажанням, дату закінчення дії — після неї ключ перестане працювати сам.
Збережіть значення ключа в надійному місці: повністю воно показується один раз. Ключ починається з fin_sk_. Потім у списку видно лише його початок.

У списку для кожного ключа видно назву, початок ключа, дати створення, спливання і останнього використання, а також лічильники запитів і помилок. Ключ можна перегенерувати (старе значення одразу перестає працювати) або видалити.

Що саме може ключ

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

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

Через API доступні:

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

Платіж, створений через API, зʼявляється в застосунку як звичайний: з датою в минулому чи сьогодні — у проведених, з майбутньою датою — у запланованих. За бажанням його можна одразу покласти у «Вхідні» на підтвердження. Стаття, створена через API, одразу видима в довідниках і формах застосунку; іконку й колір їй можна призначити пізніше в застосунку.

Документація для розробника

Базовий шлях усіх запитів — /api/v1 на адресі API-сервера OneB Finance (та сама адреса, куди застосунок надсилає свої запити; якщо не впевнені, уточніть у підтримки). Формат запитів і відповідей — JSON, успішна відповідь завжди має вигляд {"data": …}.

Ключ передається в кожному запиті одним із заголовків:

X-Api-Key: fin_sk_…

або

Authorization: Bearer fin_sk_…

Усі ідентифікатори записів — стабільні текстові коди (uuid). Їх варто зберігати у своїй системі як є. Дати платежів передаються як unix-час у секундах.

Перелік запитів

Запит	Що робить	Параметри та поля
`GET /accounts`	Активні рахунки	Відповідь: `id`, `name`, `code`, `currency`, `is_active`, `balance`
`GET /accounts/{id}/payments`	Платежі рахунку, від новіших до старіших	`date_from`, `date_to` (unix-час), `limit` (до 100, типово 50), `offset`
`POST /payments`	Створити платіж	Обовʼязково: `account_id`, `direction` (`1` — надходження, `-1` — витрата), `amount` (додатне число), `currency` (код, напр. `UAH`), `paid_at`. Необовʼязково: `category_id`, `contractor_id`, `project_id`, `comment`, `tags` (масив рядків), `state` (`processed` або `inbox`)
`PUT /payments/{id}`	Змінити платіж	Ті самі поля, усі необовʼязкові; передаються лише ті, що змінюються
`DELETE /payments/{id}`	Видалити платіж	—
`GET /contractors`	Перелік контрагентів	`search` (за назвою, повною назвою чи кодом), `limit` (до 100)
`GET /contractors/{id}`	Картка контрагента	—
`POST /contractors`	Створити контрагента	Обовʼязково: `name`. Необовʼязково: `full_name`, `code` (ЄДРПОУ / РНОКПП), `phone_number`, `address`, `notes`
`PUT /contractors/{id}`	Змінити контрагента	Ті самі поля, усі необовʼязкові
`GET /categories`	Активні статті доходів і витрат	`type` — `income` або `expense`; без нього — усі. Відповідь: `id`, `name`, `type`, `parent_id`
`POST /categories`	Створити статтю	Обовʼязково: `name`, `type` (`income` або `expense`). Необовʼязково: `parent_id` — ідентифікатор батьківської статті того самого типу
`GET /projects`	Перелік проєктів	Відповідь: `id`, `name`, `archived_at`
`GET /api-keys`	Перелік ключів простору	—
`POST /api-keys`	Створити ключ	`name`, необовʼязково `expires_at`. Повне значення ключа є лише у цій відповіді
`DELETE /api-keys/{id}`	Видалити ключ	Ключ не може видалити сам себе
`POST /api-keys/{id}/regenerate`	Перевипустити ключ	Ключ не може перевипустити сам себе

Приклад: створити вкладену статтю витрат

POST /api/v1/categories
X-Api-Key: fin_sk_…
Content-Type: application/json

{"name": "Реклама в Google", "type": "expense", "parent_id": "6f1c…-uuid-батьківської-статті"}

Відповідь 201 Created:

{"data": {"id": "b8a3…", "name": "Реклама в Google", "type": "expense", "parent_id": "6f1c…"}}

Як API повідомляє про помилки

401 — ключ не передано, він недійсний, видалений або прострочений.
404 — запис не знайдено або він належить іншому робочому простору. Тіло: {"error": "…"}. Так само відповідає створення статті, якщо батьківської статті з таким parent_id у вашому просторі немає.
422 — дані не пройшли перевірку: бракує обовʼязкового поля, невідома валюта, платіж в іншій валюті без курсу, або батьківська стаття має інший тип (дохідну статтю не можна вкласти у витратну). Тіло містить message і errors з поясненням по полях.
429 — перевищено ліміт запитів: для одного ключа діє 100 запитів на хвилину. Розробникові варто передбачити повтор через паузу.

Обмеження й нюанси

Створювати, перевипускати й видаляти ключі може лише адміністратор робочого простору.
Повне значення ключа показується лише один раз — при створенні або перевипуску. Якщо його втратили, ключ не «підглянути»: треба перегенерувати або створити новий.
Ключ дає доступ до даних усього робочого простору. Не публікуйте його і не надсилайте у відкритих каналах.
Через API статтю можна лише створити. Перейменувати, перемістити, вимкнути чи обʼєднати статті — у застосунку, в довіднику статей.
Перелік статей віддає лише активні статті; технічна стаття переказів між рахунками в ньому не показується, і платежі на неї через API не створюються.

Часті питання

Я загубив ключ. Де його подивитись? Ніде. У списку видно лише початок ключа. Натисніть «Перегенерувати» — отримаєте нове значення, але стару інтеграцію доведеться оновити.

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

Платіж створився, але я не бачу його в проведених. Перевірте дату: платіж із майбутньою датою потрапляє в заплановані. Якщо при створенні передали state: inbox, платіж чекає на підтвердження у «Вхідних».

Розробник каже, що стаття не створюється з помилкою 422. Найчастіше — батьківська стаття іншого типу: під дохідну статтю можна вкласти лише дохідну, під витратну — лише витратну. Другий типовий випадок — не передано type.

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

Дивіться також

Публічне API та API-ключі OneB Invoice — як влаштоване API сусіднього застосунку
Як підключити NovaPay для синхронізації в OneB Finance — приклад готової інтеграції без API-ключа