Когда документы начинаются в другой системе

Вопрос, который задают на второй встрече: «а вы интегрируетесь с нашей системой?». До сих пор честным ответом было «нет». Теперь ответ такой: у вас есть портал, CRM или учётная система, в которой сделка уже существует, и DocuTract может работать как её часть.

Шестая функция волны это выход наружу. Токен, которым ваша система обращается к нам, адрес, на который мы пишем сами, и открытое описание всего, что между ними.

Токен, который мы не можем показать дважды

Токен создаётся на экране Интеграции: название, по которому вы узнаете, кто им пользуется, и перечень того, что ему разрешено. Дальше он показывается один раз.

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

Отозвать выключает токен мгновенно. Запись о нём остаётся: то, что он существовал и когда перестал действовать, это часть истории рабочего пространства, а не мусор.

Разрешения проверяются на каждом адресе отдельно. Токен, которому разрешено только читать шаблоны, получит в ответ на попытку создать документ внятное «не хватает разрешения documents:write», а не пустое «не найдено». Мы исходим из того, что интеграцию настраивает живой человек, и ответ, который не объясняет причины, стоит ему вечера.

Что умеет API

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

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

Описание всех адресов и полей мы генерируем из самого кода и публикуем открыто, без токена: /api/v1/openapi.json. Документация, которую нужно сначала выпросить, это документация, которую никто не читает.

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

Спрашивать нас, готов ли документ, не нужно. Дайте адрес и отметьте события: документ готов, документ не сгенерировался, дело готово, найдено расхождение, клиент прислал файл.

Каждый запрос подписан, а секрет для проверки подписи показывается один раз, как и токен. Если ваш сервер ответил иначе или не ответил вовсе, мы повторим: через минуту, через пять, через полчаса, через два часа и через десять. Потом прекратим, потому что интеграция, которую никто не чинит, не должна пожизненно тратить чужие ресурсы.

А дальше та часть, ради которой это всё и писалось. Когда с той стороны говорят «наша система ничего не получила», ответ есть на экране: событие, время, сколько было попыток, какой код ответа и начало тела ответа. Видно, что она отвечала 500 пять раз. Это не отладочный инструмент для нас, это ответ для вашего инженера.

Рядом две кнопки для того часа, когда интеграцию ещё настраивают. Тест отправляет пробный запрос прямо сейчас, не дожидаясь настоящего события, так что приёмник можно проверить до того, как через него пойдёт работа. Повторить рядом с неудачной доставкой делает ещё одну попытку немедленно и не обнуляет историю: четыре неудачные попытки остаются в записи, потому что это правда о том, сколько стоило это сообщение.

Границы, которые мы поставили себе сами

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

API и вебхуки входят в тариф Team. Если рабочее пространство переходит на другой тариф, то, что уже создано, остаётся видимым и его можно отозвать: ключи, к которым ни у кого нет доступа, хуже, чем платная функция.

Чего в этом выпуске нет

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

Что дальше

Седьмая, последняя функция волны это пакетная генерация: список на пятьдесят строк или архив сканов вместо пятидесяти одинаковых заполнений руками, с видимым прогрессом и возможностью повторить только то, что не получилось.

Полный список есть в записи что мы строим дальше, а пошаговая инструкция для интеграций в справке.