API для первинних документів: як під'єднати свою облікову систему

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

Дві моделі обміну

Pull — ваша система питає. За розкладом, скажімо раз на п'ять хвилин, облікова система звертається до сервісу: «дай документи, оброблені після такого-то часу». Просто в реалізації, стійко до збоїв мережі, але дані приходять із затримкою до інтервалу опитування.

Push — сервіс сам сповіщає. Щойно документ розпізнано, сервіс надсилає вебхук на вашу адресу з реквізитами і посиланням на повні дані. Миттєво і без зайвих запитів, але ваш бік має бути доступний ззовні й уміти коректно приймати повторні доставки.

Робоча схема — обидві разом: вебхук як основний канал, періодичний pull як страховка на випадок, коли ваш сервер був недоступний.

Автентифікація

Стандарт — Bearer-ключ у заголовку Authorization. Три правила, які економлять нерви:

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

Вебхуки додатково підписують HMAC-підписом: ваш обробник перевіряє підпис і відкидає запити, які не від сервісу. Без цього будь-хто, хто знає вашу адресу, зможе підкинути в облік «документ».

Ідемпотентність — те, про що згадують після інциденту

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

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

Контракт полів — найдорожча помилка інтеграції

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

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

Друге питання — версіонування. Зміни контракту мають виходити новою версією (/api/v2), а стара — жити ще якийсь час. Мовчазна зміна поля у працюючій версії неприпустима.

Що робити з помилками

Хороше API не приховує невдачі. Мінімум, який має повертатись:

статус обробки документа — розпізнано, помилка, потребує перевірки;
причина помилки людською мовою, а не лише код;
ознака низької впевненості, коли розпізнано, але сумнівно.

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

На своєму боці передбачте повтори з наростаючою паузою: збій API не повинен означати втрачений документ.

План підключення, який реально працює

Прочитати документацію до першого рядка коду. Публічна, відкрита без реєстрації документація — ознака зрілого сервісу.
Тестовий контур. Окремий ключ, десяток реальних документів, порівняння результату з тим, що заведено руками.
Один постачальник у продуктив. Не вся первинка одразу, а один потік, який ви добре знаєте.
Моніторинг. Лічильник оброблених документів і алерт на помилки. Тиха інтеграція, яка стала три дні тому, — гірша за її відсутність.
Розширення. Далі решта постачальників і типів документів.

Підсумок

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

Документація DocaAI відкрита без реєстрації — docaai.com/api-docs: можна подивитись формат відповіді й структуру вебхука ще до того, як заводити акаунт.