Рано или поздно любой команде хочется, чтобы документы взаимодействовали с остальным ПО: загрузить файл из скрипта, запустить процесс по расписанию или узнать в тот же миг, когда документ обработан. В AuraDoc для этого есть два взаимодополняющих способа. REST API позволяет вашим системам попросить AuraDoc что-то сделать, а вебхуки позволяют AuraDoc сообщить вашим системам, что что-то произошло. В статье разобраны оба и детали безопасности, важные в продакшене.
API-ключи и области
Всё начинается с API-ключа. Создайте его в Dashboard › Settings › API keys, задайте имя и выберите области. Области ограничивают возможности ключа, поэтому ключу только для загрузки файлов не нужны права на управление чем-либо ещё. Ключ не может создать другой ключ с более широкими областями, а действующие права всегда равны общим для ключа и роли человека, как описано в статье роли и права команды. Запросы несут ключ в заголовке Authorization как bearer-токен.
На той же странице показана статистика использования по каждому ключу, так что видно, какая интеграция активна, а какая замолчала. На платных тарифах для отдельного ключа можно задать лимит частоты запросов, что полезно, когда один шумный скрипт не должен мешать остальным. Если ключ утёк, удалите его и создайте новый; больше ничего менять в AuraDoc не нужно.
Что умеет API
На странице интеграций в документации указан базовый адрес и приведены примеры, которые можно скопировать. Сейчас можно загрузить документ, попросить AuraDoc принять документ по URL, запустить рабочий процесс и создать запрос на подпись, каждое действие одним авторизованным запросом. Это те же операции, которые люди выполняют в панели, поэтому результат, созданный через API, отображается в интерфейсе как любой другой.
Если вы предпочитаете опрос получению вызовов, есть конечные точки триггеров: они возвращают новые документы, завершённые запуски процессов и завершённые подписи, а также каталог с их описанием. Инструменты, которые не принимают вебхуки, например дополнения для таблиц или no-code платформы, могут опрашивать их по расписанию. Полная справка на странице документации по интеграциям.
Исходящие вебхуки
Для уведомлений в реальном времени откройте Dashboard › Webhooks и добавьте конечную точку. Нужные события выбираются из списка: документ создан, классифицирован и удалён, OCR и перевод завершены или завершились ошибкой, события процессов, предупреждения о квоте хранилища и события подписей. При сохранении AuraDoc показывает секрет подписи один раз. Сразу скопируйте его в принимающий сервис; если потеряете, смените секрет, будет создан новый, а смена попадёт в журнал аудита.
Содержимое можно оформить шаблоном длиной до нескольких тысяч символов и проверить перед сохранением. Кнопка теста отправляет пример события с тестовым заголовком, чтобы убедиться, что ваша точка доступна и разбирает тело запроса, прежде чем на неё полагаться. Любой вебхук можно отключить, не удаляя, что удобно на время обслуживания.
Проверка подписей и обработка сбоев
Каждая доставка подписана. AuraDoc вычисляет HMAC-SHA256 от метки времени и исходного тела с вашим секретом и передаёт результат в заголовке подписи, а также заголовки с названием события, идентификатором вебхука, идентификатором доставки, меткой времени и номером повтора. Получателю следует пересчитать подпись по исходному телу, сравнить её за постоянное время и отклонять запросы со слишком старой меткой времени. Так никто не подделает событие для вашей точки, даже зная её адрес.
Конечные точки иногда падают, и AuraDoc это учитывает. Если доставка не удалась, она автоматически повторяется с нарастающими паузами от пяти минут до шести часов. В представлении доставок видна каждая попытка с результатом, а после исправления проблемы повтор можно запустить вручную. Поскольку при повторах используется тот же идентификатор доставки, получатель может спокойно игнорировать дубликаты. О сочетании вебхуков с файлами от облачных провайдеров читайте в статье облачные хранилища и отслеживаемые папки.