REST API
Кратко
Обработка в Documentize асинхронная: вы отправляете задачу, опрашиваете её статус и затем скачиваете результат. Веб-приложения используют именно этот REST-интерфейс (по адресу /webapi/), и self-host предоставляет тот же самый. Важная оговорка: в репозитории нет отдельного публичного справочника по API или файла с примерами запросов, поэтому воспринимайте сведения об эндпоинтах ниже как описание того, что сервис делает сегодня, а не как опубликованный версионированный контракт (проверьте, прежде чем строить на этом продукт).
Как работает асинхронная задача
- Создание. Отправьте POST с multipart-формой, содержащей ваши файлы, на маршрут операции, например
POST /webapi/compress(параметры вродеcompressTypeпередаются в строке запроса) илиPOST /webapi/merge(filesплюс параметры вродеinputType,outputType). В ответе приходит объект статуса с идентификатором задачи и именем файла или папки. - Очередь. Запрос ставится в очередь, и его подхватывает рабочий узел этого приложения; соединение вас не удерживает.
- Опрос.
POST /webapi/process_status/{id}возвращает текущее состояние. Коды статуса в ответе:203— ещё обрабатывается (продолжайте опрос; могут быть поля прогресса и сообщение о шаге),200— готово, есть ссылки для скачивания,204— ожидание или зависание (признак зависания помечает работу, которая перестала двигаться),500— ошибка. - Скачивание. Ответ о завершённой задаче перечисляет файлы результата; ссылки на файлы выглядят как
/webapi/file_url/{dir}/{file}. Результаты хранятся временно, не вечно. - Очистка.
POST /webapi/ImmediatelyRemove/{id}сразу удаляет файлы задачи. Вошедшие в систему пользователи могут получить список черезGET /webapi/my-files.
Остальные маршруты приложений устроены так же: rotate, removepages, splitdoc, convert, searchable, ocr, extract-text, extract-image, extract-metadata, resize, booklet, flatten, deskew, abstracts-generator, chat и другие.
Продолжение обработки
На бесплатном тарифе долгая задача может остановиться по лимиту времени, когда обработана только часть входных данных. Тогда в результате будет идентификатор продолжения (32 шестнадцатеричных символа):
GET /webapi/continuations/{id}показывает оставшиеся файлы.POST /webapi/continuations/{id}/continueзапускает новую задачу для них. Это бесплатно (операция не списывается), может быть доступно только после паузы (HTTP 429 сavailableFromUtc), а повторный вызов возвращает ту же задачу.DELETE /webapi/continuations/{id}отбрасывает остаток. Идентификатор истекает; отсутствующий или завершённый даёт 404.
Аутентификация и лимиты
- Анонимные запросы выполняются в рамках небольшой дневной квоты; у вошедших в систему и подписанных аккаунтов она больше (см. каналы).
- Доступ к аккаунту использует bearer-токен. Долгоживущие ключи — это ключи
dmk_, которые выдаются на странице MCP и работают какAuthorization: Bearer dmk_...; desktop-клиенты принимают токен, скопированный из веб-приложения. Принимаются ли ключиdmk_на каждом REST-маршруте, здесь не документировано (проверьте). - Запуск на бесплатном тарифе может быть ограничен (например, размером файла или лимитом страниц PDF); платная подписка снимает ограничение.
Минимальный пример
curl -F "files=@big.pdf" "https://<host>/webapi/compress?compressType=1"
# -> JSON с идентификатором задачи
curl -X POST "https://<host>/webapi/process_status/<id>"
# повторяйте, пока statusCode не станет 200, затем скачайте файлы по перечисленным URL
<host> — это сервис, с которым общается веб-приложение, либо ваш собственный self-host (http://localhost/webapi/). Точные имена полей JSON (проверьте по реальному ответу) в этой книге не фиксируются.