Сканирование через API

Сканирование через API превращает PDF в правдоподобную отсканированную копию одним REST-вызовом — это удобно для автоматических процессов и интеграций. Создайте задание, загрузите PDF, затем опрашивайте статус или дождитесь webhook: три шага из любой среды и любого языка, способного отправить HTTP-запрос. Цветовое пространство, разрешение, поворот, размытие, шум, яркость, контраст и рамка настраиваются.

Как проходит вызов

  1. Создать задание

    POST /v1/scan-jobs

    Отправьте свой config и, при желании, webhookUrl — в ответ придут jobID и предподписанный uploadURL.

  2. Загрузить PDF

    PUT {uploadURL}

    Отправьте файл методом PUT прямо на предподписанный адрес S3 из предыдущего шага — токен не нужен.

  3. Забрать отсканированную копию

    GET /v1/scan-jobs/{jobID}

    Опрашивайте статус или дождитесь webhook; как только задание станет completed, скачайте результат по downloadURL.

Где это пригодится

Пакетный выпуск на бэкенде

Договоры, счета и отчёты, созданные на сервере, сразу проходят через эффект сканирования, и никому не нужно повторять то же самое вручную на веб-странице.

Внутри существующей системы

Добавьте в CRM, ERP или систему заявок действие «выгрузить отсканированную копию» и пусть оно обращается к API.

Автоматические конвейеры

CI, n8n, Zapier и подобные платформы запускают задание по событию, а webhook по завершении передаёт работу дальше.

Большие очереди файлов

Задания асинхронные: после создания каждое обрабатывается само по себе, а ход работы виден через status и createdAfter.

Языки и среды

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLКомандная строка / CI
ЕщёЛюбой HTTP-клиент

API — это обычные HTTP и JSON, поэтому обратиться к нему может любой язык или платформа автоматизации, умеющая отправлять запросы.

Примеры кода

API Bearer Token

Токен привязан к вашей учётной записи, и его можно в любой момент создать заново. Сканирование через API требует учётной записи Pro: без действительного токена API отвечает 401, без роли Pro — 403.

Попробовать

Настройте параметры, посмотрите, как меняется тело запроса, и выполните три вызова к API.

Параметры сканирования

Пробный запуск обращается к API с вашим токеном и требует учётной записи Pro; параметры и тело запроса можно смотреть свободно.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

Информация о задании сканирования

пример
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

Справочник API

МетодПутьОписание
POST/v1/scan-jobsСоздаёт задание на сканирование. Отправьте config и, при необходимости, webhookUrl; в ответ придёт объект задания со статусом created и предподписанный uploadURL.
PUT{uploadURL}Предподписанный адрес S3 из предыдущего шага, он находится не на api.lookscanned.ioЗагружает исходный PDF с заголовками Content-Type: application/pdf и Content-Length. Адрес уже содержит подпись, поэтому заголовок Authorization добавлять не нужно.
GET/v1/scan-jobs/{jobID}Читает одно задание — для опроса статуса. При created содержит uploadURL, при completed — downloadURL.
GET/v1/scan-jobsПеречисляет ваши задания с фильтрами по jobID, status и createdAfter.
Статусcreatedprocessingcompletedfailed
  • 401 нет действительного токена
  • 403 учётная запись не Pro
  • 404 задание не найдено

Тело запроса

ПолеТипПо умолчаниюОписание
webhookUrlstring · —Вызывается один раз по завершении задания, так что опрашивать статус не нужно.
config.colorspace'gray' | 'sRGB' · graygrayЦветовое пространство итогового изображения; gray — чёрно-белая отсканированная копия.
config.resolutionnumber · 7272Разрешение итогового изображения, в DPI.
config.rotatenumber · —Поворот всего документа, в градусах.
config.rotate_varnumber · —Диапазон случайного поворота каждой страницы, в градусах — эффект криво положенного листа.
config.blurnumber · 00Сила размытия.
config.noisenumber · 00Сила шума.
config.brightnessnumber · 11Яркость; 1 оставляет её без изменений.
config.contrastnumber · 11Контраст; 1 оставляет его без изменений.
config.borderboolean · falsefalseДобавлять ли странице рамку сканирования.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegФормат изображения, в который отрисовываются страницы.

Любое поле можно не указывать. Значения, с которых начинает раздел «Попробовать» — разрешение 150, поворот 1, яркость и контраст 1,3 — это сочетание, рекомендованное веб-приложением, а не значения API по умолчанию.

Поля объекта задания, за которыми стоит следить

status
created / processing / completed / failed — определяет, присутствуют ли два адреса ниже.
uploadURL
Только пока задание в статусе created. Предподписанный адрес загрузки с ограниченным сроком действия.
downloadURL
Только после статуса completed. Предподписанный адрес скачивания с ограниченным сроком действия.
inputUploadedAt / completedAt
Когда завершилась загрузка исходника и когда завершилось задание; разница даёт время обработки.

Частые вопросы

Нужен ли Pro для сканирования через API?

Да. Без действительного токена API отвечает 401, а учётная запись без роли Pro получает 403. После перехода на Pro и входа токен будет на этой странице.

Как узнать, что задание завершено?

Двумя способами: опрашивать GET /v1/scan-jobs/{jobID} или передать webhookUrl при создании задания и позволить сервису один раз вызвать вас в ответ.

Результат такой же, как при сканировании на веб-странице?

Такой же. Обе стороны используют одну и ту же реализацию эффекта сканирования, а цветовое пространство, разрешение, поворот, размытие, шум, яркость, контраст и рамка в config соответствуют одноимённым настройкам на веб-странице: одинаковые параметры дают одинаковый результат. Различается только место обработки — локально на странице и удалённо через API.

Можно ли сохранить адреса загрузки и скачивания и использовать их повторно?

Лучше не стоит. uploadURL и downloadURL — предподписанные адреса с ограниченным сроком действия; после истечения нужно снова запросить задание и получить новые.

Сколько обрабатывается задание?

Зависит от числа страниц и разрешения. Несколько страниц обычно готовы за секунды, а более высокое разрешение и длинные документы занимают больше времени. Разница между inputUploadedAt и completedAt даёт фактическое время.

Что делать, если задание не выполнилось?

Статус станет failed. Обычные причины — файл не является корректным PDF, ограничения шифрования или прерванная загрузка. Убедитесь, что файл открывается, и создайте новое задание.

Можно ли посмотреть прошлые задания?

Да. GET /v1/scan-jobs перечисляет ваши задания и поддерживает фильтры по jobID, status и createdAfter — этого достаточно для сверки или повторного скачивания.