API

API Скапибары позволяет с легкостью реализовать функционал сканирования документов со сканнеров TWAIN/WIA/SANE в своих собственных программных решениях. API позволяет выполнять сканирование с заданными опциями и конвертацию результатов сканирования в PDF через HTTP API.

API не зависит от языка программирования, фреймворка и платформы: обращаться к нему можно и из веб-приложения, и из десктопной программы — достаточно возможности отправить обычный HTTP-запрос на локальный адрес.

Scapybara избавляет разработчиков от необходимости самостоятельно интегрироваться с низкоуровневыми драйверами сканеров и разбираться в особенностях протоколов TWAIN, WIA и SANE на разных платформах. Вместо этого достаточно отправить обычный HTTP-запрос — а всю работу с оборудованием Скапибара берёт на себя.

Перед началом

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

Базовый адрес

Все запросы выполняются к локальному серверу Скапибары:

http://127.0.0.1:10765

Порт фиксированный. Дальше в примерах адрес сервера опускается — указан только путь запроса.

Типовая последовательность вызовов

GET /ping — проверить, что Скапибара запущена, и узнать, доступно ли распознавание текста.
GET /devices — получить список подключенных сканеров и выбрать нужный.
GET /paperSources и GET /options — узнать доступные источники (стекло, автоподатчик) и их опции для выбранного устройства.
POST /scanPages — отсканировать страницы с выбранными опциями.
POST /pagesToPdf — собрать отсканированные страницы в PDF.

Отдельно живут запросы лицензии (/license/*) — они нужны при первом запуске на новом устройстве.

Сервер

Проверка доступности сервера

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

Пример запроса:

GET /ping

Пример ответа:

{
  "message": "pong",
  "apiVersion": 1,
  "wsVersion": 1,
  "ocr": true,
  "status": "success"
}

Поля ответа:

apiVersion - Версия HTTP API

wsVersion - Версия WebSocket API

ocr - Доступно ли распознавание текста

Устройства

Получение списка устройств (сканеров)

Пример запроса:

GET /devices

Пример ответа:

{
  "devices": [
    {
      "deviceId": "twain:TWAIN Working Group:TWAIN2 Software Scanner",
      "vendor": "TWAIN Working Group",
      "model": "TWAIN2 Software Scanner",
      "type": "unknown"
    }
  ],
  "status": "success"
}

Получение доступных источников для устройства

Параметры запроса:

deviceId - ID устройства

Пример запроса:

GET /paperSources?deviceId=twain:TWAIN Working Group:TWAIN2 Software Scanner

Пример ответа:

{
  "paperSources": [
    "flatbed",
    "feeder"
  ],
  "status": "success"
}

Получение доступных опций для источника устройства

Параметры запроса:

deviceId - ID устройства

paperSource - Источник

Пример запроса:

GET /options?deviceId=twain:TWAIN Working Group:TWAIN2 Software Scanner&paperSource=flatbed

Пример ответа:

{
  "options": {
    "autofeed": {
      "name": "autofeed",
      "title": "autofeed",
      "desc": "autofeed",
      "capabilities": 8,
      "valueType": 0,
      "valueUnit": 0,
      "constraint": {
        "type": 2,
        "range": {},
        "list": [
          "true",
          "false"
        ]
      },
      "value": "true",
      "isReadable": true,
      "isWritable": true
    },
    (...)
  },
  "status": "success"
}

Сканирование

Сканирование страниц

Параметры запроса:

deviceId - ID устройства

paperSource - Источник

Пример запроса:

POST /scanPages?deviceId=twain:TWAIN Working Group:TWAIN2 Software Scanner&paperSource=flatbed

{
  "options": {
    "bit_depth": "24",
    "brightness": "0",
    "contrast": "0",
    "mode": "Color",
    "resolution": "300"
  }
}

Пример ответа:

{
  "pages": [
    "{JPEG в BASE64}"
  ],
  "status": "success"
}

Конвертирование страниц в PDF

Параметры запроса:

pages - Страницы сканирования в формате JPEG, закодированные в BASE64

textLayer - Добавить в документ текстовый слой. Если параметр не задан, слой добавляется при наличии распознавания на компьютере пользователя (поле ocr в ответе GET /ping)

Пример запроса:

POST http://127.0.0.1:10765/pagesToPdf

{
  "pages": [
    "{JPEG в BASE64}"
  ],
  "textLayer": true
}

Пример ответа:

{
  "pdf": "{PDF в BASE64}",
  "textLayer": true,
  "status": "success"
}

Поля ответа:

pdf - Готовый документ, закодированный в BASE64

textLayer - Добавлен ли текстовый слой в действительности

PDF с текстовым слоем

Распознанный текст ложится в документ невидимым слоем поверх изображения: страница остаётся сканом, но текст в PDF можно искать и копировать.

Распознавание идёт на компьютере пользователя и занимает несколько секунд на страницу, поэтому запрос с текстовым слоем выполняется заметно дольше. Если распознавание недоступно, сервер всё равно вернёт документ — без текстового слоя и с textLayer: false в ответе.

Лицензия

Получение идентификатора устройства

Пример запроса:

GET http://127.0.0.1:10765/license/deviceId

Пример ответа:

{
    "deviceId": "40ba583c0605bae5a75cda41f65b8ba11ebca6cef0255e1e030b5b53befeccd6",
    "status": "success"
}

Активация лицензии

Параметры запроса:

key - Ключ активации

Пример запроса:

GET http://127.0.0.1:10765/license/activate?key=VT3VR-IJ3T6-28LE6-PXDTA-CR5HU

Пример ответа:

{
    "message": "License activated",
    "status": "success"
}

Получение информации о лицензии

Пример запроса:

GET http://127.0.0.1:10765/license

Пример ответа:

{
  "license": {
    "k": "VT3VR-IJ3T6-28LE6-PXDTA-CR5HU",
    "t": "40ba583c0605bae5a75cda41f65b8ba11ebca6cef0255e1e030b5b53befeccd6",
    "iat": "2024-09-01T12:30:45.000Z",
    "eat": "2024-10-01T12:30:45.000Z",
    "vat": "2024-09-02T12:30:45.000Z",
    "tags": null
  },
  "licenseStatus": "ok",
  "status": "success"
}

JS-виджет

Предыдущая страница

Лицензионное соглашение

Следующая страница