Обзор
HTTP API на https://api.libscanner.com: распознавание кодов на снимке, создание DataMatrix и QR, разбор и проверка строки GS1. Внутри — те же ридеры, что продаются как библиотеки unir и dmr, и тот же генератор, что dmgen.
| Метод | Что делает | Стоимость |
|---|---|---|
POST /v1/decode | Читает DataMatrix, QR, Code 128, GS1-128 и EAN/UPC на снимке JPEG или PNG | 1 запрос |
POST /v1/generate | Создаёт PNG с DataMatrix (в том числе GS1 и «Честный знак») или QR Code | 1 запрос |
POST /v1/gs1/parse | Разбирает строку кода на поля GS1 и проверяет её структуру — без снимка | 0,1 запроса |
GET /v1/usage | Тариф ключа, расход и остаток лимитов | бесплатно |
Все ответы — JSON в UTF-8 (кроме PNG из /v1/generate). Цены и лимиты тарифов — на странице API.
Ключ и вход
- Зарегистрируйтесь на сайте и подтвердите почту — без подтверждения API отвечает 403.
- В личном кабинете, раздел «API», выпустите ключ. Он показывается один раз; на сервере хранится только его хеш. Ключей может быть несколько — например, по ключу на систему; у каждого свои права:
decodeиgenerate. - Передавайте ключ в каждом запросе — одним из двух заголовков:
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.pngPOST /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. Ровно одно из двух.
| Параметр | Значения | Смысл |
|---|---|---|
mode | single, multi | single (по умолчанию) — до первого найденного кода, быстро; multi — все коды на снимке, до 64 |
symbologies | datamatrix, qr, code128, gs1-128, ean | что искать, через запятую; по умолчанию — всё. Чем уже список, тем быстрее |
budget_ms | 100–3000 | срок на снимок, мс; по умолчанию 1000. Запрос с большим значением получает 3000 мс, остальные — срок по умолчанию; действовавший срок — в budget_ms ответа |
gs1 | true, false | добавить к каждому коду разбор полей GS1 и проверку структуры |
lang | ru, 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}
}| Поле | Смысл |
|---|---|
status | ok — прочитан хотя бы один код; not_found — кода на снимке не найдено; not_decoded — символ найден, но не прочитан (смазан, обрезан, повреждён). Ответ 200 при любом значении: снимок принят и обработан |
elapsed_ms, budget_ms | время распознавания (без передачи снимка) и действовавший срок |
codes[].symbology | datamatrix, 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 |
symbology | datamatrix, qr | вид кода; по умолчанию datamatrix |
gs1 | off, gs1, cz | только DataMatrix: gs1 — проверить данные по правилам GS1 и закодировать как GS1 DataMatrix; cz — то же плюс профиль «Честного знака»; по умолчанию off |
ecc | L, M, Q, H | только QR: уровень коррекции ошибок (около 7, 15, 25 и 30 % символа); по умолчанию H |
module_px | 1–40 | пикселей на модуль; по умолчанию 8 |
quiet_zone | 1–16 | ширина тихой зоны, модулей; по умолчанию 2 у DataMatrix и 4 у QR |
format | png | формат картинки |
lang | ru, 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⟩» |
lang | ru, 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 | Когда |
|---|---|---|
| 400 | INVALID_PARAMETER, IMAGE_REQUIRED, IMAGE_URL_INVALID, IMAGE_URL_FORBIDDEN, IMAGE_TOO_COMPLEX | неверный параметр; нет снимка; ссылка не годится или ведёт во внутреннюю сеть; у JPEG слишком много прогрессивных проходов |
| 401 | INVALID_KEY | ключа нет, он неверный или отозван |
| 403 | SCOPE, EMAIL_NOT_VERIFIED | у ключа нет прав на метод; почта учётной записи не подтверждена |
| 413 | IMAGE_TOO_LARGE | снимок больше 8 МБ, 4096 пикселей по стороне или 16 Мп |
| 415 | UNSUPPORTED_IMAGE | не JPEG и не PNG |
| 422 | INVALID_IMAGE, IMAGE_URL_UNAVAILABLE, GS1_INVALID, DATA_INVALID | файл снимка повреждён; по ссылке нет ответа 200 за 5 секунд; данные не проходят проверку GS1 или не помещаются в символ |
| 429 | DAY_LIMIT, MONTH_LIMIT | исчерпан лимит тарифа; в теле — usage, в заголовке Retry-After — секунды до сброса |
| 429 | RATE_LIMIT, CONCURRENCY_LIMIT | больше 5 запросов в секунду или 2 одновременных на ключ (или 20 ссылок в минуту); с Retry-After |
| 503 | BUSY | сервер занят или 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, или поток кадров с камеры — доработаем под вашу задачу или подберём библиотеку. Напишите нам →