Коли документи починаються в іншій системі

Питання, яке ставлять на другій зустрічі: «а ви інтегруєтесь з нашою системою?». Досі чесною відповіддю було «ні». Тепер відповідь така: у вас є портал, CRM чи облікова система, у якій угода вже існує, і DocuTract може працювати як її частина.

Шоста функція хвилі це вихід назовні. Токен, яким ваша система звертається до нас, адреса, на яку ми пишемо самі, і відкритий опис усього, що між ними.

Токен, який ми не можемо показати двічі

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

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

Відкликати вимикає токен миттєво. Запис про нього лишається: те, що він існував і коли перестав діяти, це частина історії робочого простору, а не сміття.

Дозволи перевіряються на кожній адресі окремо. Токен, якому дозволено лише читати шаблони, отримає у відповідь на спробу створити документ виразне «не вистачає дозволу documents:write», а не порожнє «не знайдено». Ми вважаємо, що інтеграцію налаштовує жива людина, і відповідь, яка не пояснює причини, коштує їй вечора.

Що вміє API

Стільки ж, скільки і ви на екрані, тільки без екрана: відкрити справу і завантажити в неї скани, створити документ із шаблона одразу зі значеннями, спитати, на якій він стадії, забрати всі значення разом із тим, з якого скана кожне прочитано, і отримати короткочасне посилання на готовий файл.

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

Опис усіх адрес і полів ми генеруємо з самого коду і публікуємо відкрито, без токена: /api/v1/openapi.json. Документація, яку треба спершу випросити, це документація, яку ніхто не читає.

Вебхуки і чесний журнал

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

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

А далі та частина, заради якої це все й писалося. Коли з того боку кажуть «наша система нічого не отримала», відповідь є на екрані: подія, час, скільки було спроб, який код відповіді і початок тіла відповіді. Видно, що вона відповідала 500 пʼять разів. Це не налагоджувальний інструмент для нас, це відповідь для вашого інженера.

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

Межі, які ми поставили собі самі

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

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

Чого в цьому випуску немає

Бриф цієї фази описував ще дві частини: вивантаження готового документа в Google Drive, OneDrive чи Dropbox і відправлення на підпис через DocuSign або Dropbox Sign. Обидві вимагають облікових даних цих провайдерів, яких у нас зараз немає, а писати інтеграцію, яку ніде перевірити, означає видавати ненаписаний код за готовий. Вони лишаються в плані окремими випусками.

Що далі

Сьома, остання функція хвилі це пакетна генерація: список на п'ятдесят рядків або архів сканів замість п'ятдесяти однакових заповнень руками, з видимим прогресом і можливістю повторити тільки те, що не вийшло.

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