Публічне API та API-ключі (бета)

Функція в бета-режимі, вмикається в Налаштування → Ранні функції (у меню — «Експериментальні функції»). Докладніше про такі функції — у статті Експериментальні функції.

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

Де це в застосунку: Налаштування → API Keys.

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

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

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

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

У списку для кожного ключа видно назву, початок ключа, дати створення, спливання і останнього використання, а також кнопки «Перегенерувати» і «Видалити».

1.00

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

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

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

Через API доступні документи (рахунки, акти й інші типи), клієнти, товари та їхні категорії, профілі компаній, валюти, способи оплати, платежі з OneB Finance, зведені показники дашборда, розклади регулярних рахунків, а також керування вебхуками та самими API-ключами. Документ можна створити, оновити, змінити статус, видалити, отримати його PDF, увімкнути публічне посилання й створити з нього дочірній документ.

Документи, створені через API, видно в застосунку

Документ, який ваша система створила з API-ключем, у застосунку позначається смужкою «Створено через API» на картці документа і стрічкою «API» у списку — так само, як позначаються рахунки, що приходять з Prom.ua. Автором такого документа вважається не користувач, який створив ключ, а «API». Це допомагає бухгалтеру відрізнити власні чернетки від тих, що надійшли з іншої системи.

Те саме джерело передається і розробникові: у відповідях API та у вебхуках є поле source зі значенням «користувач», «API» або назва інтеграції. Так ваша система може відбирати лише свої документи.

Що ще повідомляє API про документ

Крім основних даних документа, розробникові доступні:

час публікації (shared_at) — коли документ востаннє поділили з клієнтом кнопкою «Поділитись» або через API; для чернетки значення порожнє. Зручно, щоб ваша система реагувала саме на момент виставлення рахунка, а не на будь-яке редагування;
коротке публічне посилання (short_url) — у відповідь на запит публічного посилання API повертає і повний, і скорочений варіант. Скорочене — те саме, що показує кнопка «Поділитись» у застосунку, його зручно надсилати клієнту. Якщо сервіс скорочення тимчасово недоступний, замість короткого повертається повне посилання, тож ваша система завжди має робочий варіант;
рахунок-зразок (recurring_source_id) — у рахунку, створеному за розкладом, це посилання на рахунок, з якого зроблено розклад; за ним же можна відфільтрувати список документів.

Про публічне посилання, його захист і термін дії — у статті Публічне посилання на документ.

Регулярні рахунки через API

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

Важливо для розробника:

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

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

Базовий шлях усіх запитів — /api/public/v1 на адресі вашого застосунку. Технічна документація відкривається без ключа за тією самою адресою з додаванням /api/public/v1/docs — наприклад, посиланням «API documentation» у шапці екрана «API Keys». Її можна спокійно надіслати розробникові ще до того, як ви заведете ключ. Там перелічені всі запити, поля та приклади відповідей.

Усі ідентифікатори записів у API — стабільні текстові коди (наприклад, документ виглядає як inv_…, клієнт — як cli_…). Їх варто зберігати у своїй системі як є.

Idempotency-Key: захист від дублів

Уявіть: ваша система надіслала запит на створення рахунка, звʼязок обірвався, відповідь не дійшла. Повторити запит страшно — раптом рахунок уже створився і буде другий.

Саме для цього є заголовок Idempotency-Key. Розробник додає до запиту довільний унікальний рядок — «номер спроби». Далі:

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

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

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

Публічне API — рання (експериментальна) функція: поки ви не увімкнете «API Keys» у Налаштування → Ранні функції, пункту меню просто не буде. Крім того, доступ до API входить не в кожен тарифний план — на пункті меню може зʼявитись іконка корони. Див. Експериментальні функції і Тарифний план і ліміти.

Створювати, перевипускати й видаляти ключі може лише користувач із правами адміністратора робочого простору. Див. Користувачі й ролі робочого простору.

Для одного ключа діє обмеження 120 запитів на хвилину. При перевищенні система тимчасово відмовляє — розробникові варто передбачити повтор через паузу.

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

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

Документи, створені через API, підпорядковуються тим самим правилам, що й створені вручну: редагування опублікованого документа повертає його в чернетку, і його треба поділитися з клієнтом знову. Див. Статуси документів.

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

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

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

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

Розробник питає, який базовий шлях використовувати. /api/public/v1 на адресі вашого застосунку. Повний перелік запитів — у документації за посиланням «API documentation».

Як відрізнити документи, створені моєю системою, від тих, що завели вручну? У застосунку — за смужкою «Створено через API» на картці документа. У відповідях API та вебхуках — за полем source.

Чи можна через API виставляти рахунки щомісяця автоматично? Так: створіть для рахунку розклад — і застосунок сам виставлятиме наступні рахунки в день дати. Докладніше — у розділі «Регулярні рахунки через API» вище і в статті Регулярні рахунки.

Чи можна отримувати події замість того, щоб постійно опитувати API? Так, для цього є Webhooks.

Що може змінитися

Функція в бета-режимі. Набір доступних запитів і полів у відповідях може розширюватись, зʼявлятимуться нові події та можливості. Ми намагаємось не ламати наявні інтеграції, але поки функція в беті радимо: не покладатись на недокументовані поля і час від часу звірятися з документацією.