Документация разработчика

API распознавания и создания кодов

HTTP API: снимок — в запрос, коды DataMatrix, QR, Code 128, GS1-128 и EAN — в ответ; создание DataMatrix и QR, разбор полей GS1 и проверка структуры кода «Честного знака».

4 методараспознать, создать код, разобрать строку GS1, узнать остаток лимитов
300 запросовв месяц бесплатно, 30 в сутки — ключ в личном кабинете
OpenAPI 3.1спецификация — https://api.libscanner.com/openapi.json

Для ИИ-ассистентов: эта страница в Markdown · вся документация одним файлом · llms.txt

Версия 1.0

Обзор

HTTP API на https://api.libscanner.com: распознавание кодов на снимке, создание DataMatrix и QR, разбор и проверка строки GS1. Внутри — те же ридеры, что продаются как библиотеки unir и dmr, и тот же генератор, что dmgen.

МетодЧто делаетСтоимость
POST /v1/decodeЧитает DataMatrix, QR, Code 128, GS1-128 и EAN/UPC на снимке JPEG или PNG1 запрос
POST /v1/generateСоздаёт PNG с DataMatrix (в том числе GS1 и «Честный знак») или QR Code1 запрос
POST /v1/gs1/parseРазбирает строку кода на поля GS1 и проверяет её структуру — без снимка0,1 запроса
GET /v1/usageТариф ключа, расход и остаток лимитовбесплатно

Все ответы — JSON в UTF-8 (кроме PNG из /v1/generate). Цены и лимиты тарифов — на странице API.

Ключ и вход

  1. Зарегистрируйтесь на сайте и подтвердите почту — без подтверждения API отвечает 403.
  2. В личном кабинете, раздел «API», выпустите ключ. Он показывается один раз; на сервере хранится только его хеш. Ключей может быть несколько — например, по ключу на систему; у каждого свои права: decode и generate.
  3. Передавайте ключ в каждом запросе — одним из двух заголовков:
Authorization: Bearer lsk_live_…
X-API-Key: lsk_live_…

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

Быстрый старт

Снимок файлом — телом запроса, с разбором полей GS1:

curl "https://api.libscanner.com/v1/decode?gs1=true" \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: image/jpeg" \
  --data-binary @label.jpg

Создать DataMatrix «Честного знака» и сохранить PNG:

curl https://api.libscanner.com/v1/generate \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"data": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz", "gs1": "cz", "module_px": 10}' \
  -o code.png

POST /v1/decode

Снимок — JPEG или PNG до 8 МБ, до 4096 пикселей по стороне и 16 Мп. Передаётся одним из трёх способов:

  • Телом запроса — Content-Type: image/jpeg или image/png (подойдёт и application/octet-stream: формат определяется по сигнатуре файла). Параметры — в строке запроса.
  • Формой multipart/form-data — файл в поле image, параметры — полями формы или в строке запроса.
  • JSON — image_base64 (файл в base64, можно data:-адресом, как его отдаёт браузер) либо image_url; параметры — полями того же JSON. Ровно одно из двух.
ПараметрЗначенияСмысл
modesingle, multisingle (по умолчанию) — до первого найденного кода, быстро; multi — все коды на снимке, до 64
symbologiesdatamatrix, qr, code128, gs1-128, eanчто искать, через запятую; по умолчанию — всё. Чем уже список, тем быстрее
budget_ms100–3000срок на снимок, мс; по умолчанию 1000. Запрос с большим значением получает 3000 мс, остальные — срок по умолчанию; действовавший срок — в budget_ms ответа
gs1true, falseдобавить к каждому коду разбор полей GS1 и проверку структуры
langru, enязык названий полей GS1 и текстов проверки; по умолчанию ru

Форма с файлом:

curl https://api.libscanner.com/v1/decode \
  -H "Authorization: Bearer lsk_live_…" \
  -F image=@label.png -F mode=multi -F symbologies=datamatrix,qr

Снимок по ссылке:

curl https://api.libscanner.com/v1/decode \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/label.jpg", "mode": "multi", "gs1": true}'

image_url — только публичный адрес http или https на портах 80 и 443. Снимок скачивается с тайм-аутом 5 секунд, не больше двух перенаправлений; адреса внутренних сетей и петли отклоняются (400 IMAGE_URL_FORBIDDEN). Таких запросов — не больше 20 в минуту на учётную запись.

Ответ распознавания

{
  "status": "ok",
  "elapsed_ms": 41.2,
  "budget_ms": 1000,
  "codes": [{
    "symbology": "datamatrix",
    "text": "0104601234567893215Abc12Xyz!-\u001d93dGVz",
    "text_hri": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz",
    "bytes_base64": "MDEwNDYwMTIzNDU2Nzg5MzIxNUFiYzEyWHl6IS0dOTNkR1Z6",
    "quad": [[212.5, 98.0], [431.0, 101.5], [428.5, 320.0], [210.0, 316.5]],
    "gs1": {
      "fields": {"01": "04601234567893", "21": "5Abc12Xyz!-", "93": "dGVz"},
      "elements": [{"ai": "01", "name": "GTIN", "value": "04601234567893"}, …],
      "check": [{"level": "ok", "text": "GTIN 04601234567893: контрольная цифра верна."}, …]
    }
  }],
  "usage": {"day": 12, "day_limit": 1000, "month": 340, "month_limit": 10000}
}
ПолеСмысл
statusok — прочитан хотя бы один код; not_found — кода на снимке не найдено; not_decoded — символ найден, но не прочитан (смазан, обрезан, повреждён). Ответ 200 при любом значении: снимок принят и обработан
elapsed_ms, budget_msвремя распознавания (без передачи снимка) и действовавший срок
codes[].symbologydatamatrix, qr, code128, gs1-128, ean-13, ean-8, upc-a, upc-e
codes[].textтекст кода; разделитель GS1 — настоящий символ U+001D, а не текст «<GS>». Байты, которые не являются правильным UTF-8, толкуются как ISO-8859-1
codes[].bytes_base64точные байты символа — для сверки и хранения кода маркировки без потерь
codes[].quadчетыре угла символа на снимке, пиксели, [x, y]
codes[].text_hri, codes[].gs1только с gs1=true: запись для человека «(01)…(21)…» и разбор (fields — идентификатор → значение, первое при повторе; elements — все поля по порядку с названиями; check — проверки с уровнем ok, warn или error). У кода, который не является строкой GS1, gs1 — null
usageрасход за сутки и за период с лимитами тарифа — уже с этим запросом

POST /v1/generate

Тело — JSON. По умолчанию создаётся DataMatrix (ГОСТ Р ИСО/МЭК 16022), с symbology: "qr" — QR Code (ИСО/МЭК 18004). Ответ — PNG; с заголовком Accept: application/json — JSON с картинкой в base64 и размерами.

ПараметрЗначенияСмысл
dataстрокачто закодировать (обязательно): до 3116 байт у DataMatrix, до 7089 у QR
symbologydatamatrix, qrвид кода; по умолчанию datamatrix
gs1off, gs1, czтолько DataMatrix: gs1 — проверить данные по правилам GS1 и закодировать как GS1 DataMatrix; cz — то же плюс профиль «Честного знака»; по умолчанию off
eccL, M, Q, Hтолько QR: уровень коррекции ошибок (около 7, 15, 25 и 30 % символа); по умолчанию H
module_px1–40пикселей на модуль; по умолчанию 8
quiet_zone1–16ширина тихой зоны, модулей; по умолчанию 2 у DataMatrix и 4 у QR
formatpngформат картинки
langru, enязык объяснения ошибки в данных

Разделитель групп в данных GS1 — байт 0x1D, текст <GS> или запись со скобками (01)…(21)…. Данные, не прошедшие проверку, — ответ 422 GS1_INVALID с объяснением, что не так («GTIN …: неверная контрольная цифра»); данные, которые не помещаются в символ, — 422 DATA_INVALID.

curl https://api.libscanner.com/v1/generate \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"data": "https://libscanner.com", "symbology": "qr", "ecc": "M"}'

{"format": "png", "symbology": "qr", "width": 264, "height": 264, "size": "25x25",
 "image_base64": "iVBORw0KGgo…", "usage": {"day": 3, "day_limit": 30, "month": 3, "month_limit": 300}}

size — размер символа в модулях, строки × столбцы; width и height — размер картинки с тихой зоной, пиксели.

POST /v1/gs1/parse

Разбор строки кода без снимка — например, строки, прочитанной сканером штрихкодов. Поля GS1, контрольная цифра GTIN, длина и символы серийного номера, наличие и длины кодов проверки «Честного знака» (91 + 92 или 93), пропущенные разделители, срок годности. Проверяется формат кода; статус товара в системе маркировки не запрашивается. Стоит 0,1 запроса.

ПараметрЗначенияСмысл
codeстрока до 4096 байтстрока кода (обязательно); разделитель — байт 0x1D, «<GS>» или «⟨GS⟩»
langru, enязык названий полей и текстов проверки; по умолчанию ru
curl https://api.libscanner.com/v1/gs1/parse \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"code": "0104601234567893215Abc12Xyz!-<GS>93dGVz"}'

Ответ: is_gs1, text (строка с разделителями, приведёнными к U+001D), text_hri, fields, elements, check — как в ответе распознавания — и usage. Строка, которая не разбирается как GS1, — не ошибка: is_gs1: false, fields: null и одно пояснение в check. Пункт проверки про срок годности помечен "kind": "expiry".

GET /v1/usage

Тариф и остаток лимитов; не списывается.

curl https://api.libscanner.com/v1/usage -H "Authorization: Bearer lsk_live_…"

{"plan": {"paid": false, "slug": "free", "name": "Free", "valid_until": null},
 "usage": {"day": 4.1, "day_limit": 30, "month": 57.3, "month_limit": 300},
 "day_resets_at": "2026-11-19T21:00:00Z", "month_resets_at": "2026-11-30T21:00:00Z"}

month_resets_at — конец календарного месяца у бесплатного тарифа и конец текущего оплаченного периода у платных. Дробные значения — от разборов строк по 0,1 запроса.

Лимиты и учёт

  • У тарифа — лимит запросов в сутки и за период, общий на все ключи учётной записи. Сутки — с 00:00 по московскому времени. Бесплатный тариф — 30 запросов в сутки и 300 в календарный месяц.
  • Списывается только принятый запрос: распознавание и создание — 1 запрос, разбор строки — 0,1. Ответ not_found списывается: снимок принят и обработан.
  • Не списываются: отказы 4xx (негодный снимок, неверный параметр, исчерпанный лимит), 503 и сбои на нашей стороне (5xx), а также GET /v1/usage.
  • На ключ — не больше 5 запросов в секунду и 2 одновременных; запросов с image_url — не больше 20 в минуту на учётную запись.

Ошибки

Вид ошибки — {"error": {"code", "message", "request_id"}}. Поле code постоянно — по нему и ветвитесь; message — для человека и может меняться. request_id назовите в письме в поддержку.

ОтветcodeКогда
400INVALID_PARAMETER, IMAGE_REQUIRED, IMAGE_URL_INVALID, IMAGE_URL_FORBIDDEN, IMAGE_TOO_COMPLEXневерный параметр; нет снимка; ссылка не годится или ведёт во внутреннюю сеть; у JPEG слишком много прогрессивных проходов
401INVALID_KEYключа нет, он неверный или отозван
403SCOPE, EMAIL_NOT_VERIFIEDу ключа нет прав на метод; почта учётной записи не подтверждена
413IMAGE_TOO_LARGEснимок больше 8 МБ, 4096 пикселей по стороне или 16 Мп
415UNSUPPORTED_IMAGEне JPEG и не PNG
422INVALID_IMAGE, IMAGE_URL_UNAVAILABLE, GS1_INVALID, DATA_INVALIDфайл снимка повреждён; по ссылке нет ответа 200 за 5 секунд; данные не проходят проверку GS1 или не помещаются в символ
429DAY_LIMIT, MONTH_LIMITисчерпан лимит тарифа; в теле — usage, в заголовке Retry-After — секунды до сброса
429RATE_LIMIT, CONCURRENCY_LIMITбольше 5 запросов в секунду или 2 одновременных на ключ (или 20 ссылок в минуту); с Retry-After
503BUSYсервер занят или API временно выключен; повторите через Retry-After секунд, запрос не списан

Повторять имеет смысл 429 с RATE_LIMIT/CONCURRENCY_LIMIT и 503 — после паузы из Retry-After. Остальные 4xx повтор не исправит.

Хранение снимков

  • На платных тарифах снимки не хранятся — ни прочитанные, ни непрочитанные.
  • На бесплатном тарифе снимки, на которых код не найден или не прочитан, хранятся до года для улучшения распознавания. Прочитанные снимки не хранятся.
  • Коды из ответов не сохраняются ни на одном тарифе; в учёт попадает только число запросов.
  • Серверы находятся в России.

OpenAPI

Полная спецификация (OpenAPI 3.1, на английском) — https://api.libscanner.com/openapi.json. По ней строятся клиенты (openapi-generator), её понимают Postman и Insomnia, и её же читают ИИ-ассистенты. Кроме того, в Python — вкладка Python этой документации.

Нужен метод, которого нет в API, или поток кадров с камеры — доработаем под вашу задачу или подберём библиотеку. Напишите нам →