Для разработчиков

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

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

Получить ключ Документация · Спецификация OpenAPI

С чего начать

  1. Зарегистрируйтесь и подтвердите почту.
  2. В личном кабинете, раздел «API», выпустите ключ — он показывается один раз.
  3. Передавайте ключ в заголовке Authorization: Bearer … (или X-API-Key).

Распознать коды на снимке

POST /v1/decode. Снимок — JPEG или PNG до 8 МБ, до 4096 пикселей по стороне и 16 Мп: телом запроса, полем image формы multipart/form-data либо в JSON — image_base64 или ссылкой image_url.

# Снимок файлом: JPEG или PNG телом запроса
curl https://api.libscanner.com/v1/decode?gs1=true \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: image/jpeg" \
  --data-binary @label.jpg

Параметры — в строке запроса, полями формы или JSON:

modesingle — первый найденный код, быстро (по умолчанию); multi — все коды на снимке, до 64
symbologiesчто искать, через запятую: datamatrix, qr, code128, gs1-128, ean; по умолчанию — всё
budget_msсрок на снимок, 100–3000 мс, по умолчанию 1000; действовавший срок возвращается в ответе
gs1true — разбор полей GS1 и проверка структуры у каждого кода
langru или en — язык названий полей и текстов проверки

Снимок по ссылке и все коды на нём:

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}'

Ответ

{
  "status": "ok",
  "elapsed_ms": 41,
  "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}
}

Разделитель GS в поле text — настоящий символ (U+001D), а не текст «<GS>»; точные байты символа — в bytes_base64, углы кода на снимке — в quad. Поле status: ok — код прочитан, not_found — код не найден, not_decoded — символ найден, но не прочитан.

Создать DataMatrix или QR

POST /v1/generate. По умолчанию — DataMatrix; с symbology = qr — QR Code (уровень коррекции — ecc: L, M, Q или H, по умолчанию H). У DataMatrix с gs1 = gs1 или cz данные проверяются по правилам GS1 (cz — ещё и по профилю «Честного знака») и кодируются как GS1 DataMatrix; ошибка в данных — ответ 422 с объяснением. Ответ — PNG; с заголовком Accept: application/json — JSON с картинкой в base64 и размерами.

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/gs1/parse — без снимка: поля GS1, контрольная цифра GTIN, длина и символы серийного номера, наличие и длины кодов проверки (91 + 92 или 93), пропущенные разделители, срок годности. Проверяется формат кода; статус товара в системе маркировки не запрашивается.

curl https://api.libscanner.com/v1/gs1/parse \
  -H "Authorization: Bearer lsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"code": "0104601234567893215Abc12Xyz!-<GS>93dGVz"}'

Python и 1С

import requests

API = "https://api.libscanner.com/v1"
HEADERS = {"Authorization": "Bearer lsk_live_…"}

with open("label.jpg", "rb") as f:
    r = requests.post(f"{API}/decode", params={"mode": "multi", "gs1": "true"},
                      headers={**HEADERS, "Content-Type": "image/jpeg"}, data=f)
r.raise_for_status()
for code in r.json()["codes"]:
    print(code["symbology"], code.get("text_hri") or code["text"])
    for item in (code.get("gs1") or {}).get("check", []):
        print("  ", item["level"], item["text"])
Соединение = Новый HTTPСоединение("api.libscanner.com", 443,,,,, Новый ЗащищенноеСоединениеOpenSSL);
Запрос = Новый HTTPЗапрос("/v1/decode?gs1=true");
Запрос.Заголовки.Вставить("Authorization", "Bearer lsk_live_…");
Запрос.Заголовки.Вставить("Content-Type", "image/jpeg");
Запрос.УстановитьТелоИзДвоичныхДанных(Новый ДвоичныеДанные("C:\label.jpg"));
Ответ = Соединение.ОтправитьДляОбработки(Запрос);

Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
Результат = ПрочитатьJSON(Чтение);
Для Каждого Код Из Результат.codes Цикл
    Сообщить(Код.text_hri);
КонецЦикла;

Тарифы и лимиты

Лимиты — на учётную запись, общие на все её ключи. Сутки — с 00:00 по московскому времени. Кроме того, на ключ — не больше 5 запросов в секунду и 2 одновременных.

ТарифЦенаЗапросов за периодВ сутки
Бесплатный0 ₽300 · календарный месяц30Получить ключ
API Старт · Месяц990 ₽ / 30 дней10 0001 000Подключить
API Старт · Год10 000 ₽ / 365 дней10 0001 000Подключить
API Бизнес · Месяц2 990 ₽ / 30 дней50 0005 000Подключить
API Бизнес · Год30 000 ₽ / 365 дней50 0005 000Подключить

НДС не облагается (УСН, ст. 346.11 НК РФ)

Больше 50 000 запросов в месяц или поток кадров с камеры — дешевле и быстрее библиотека: она работает на вашей машине, без сети и без задержки на передачу снимка. Библиотеки →

Что считается запросом

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

Ошибки

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

401 INVALID_KEYключа нет, он неверный или отозван
403 SCOPEу ключа нет прав на этот метод
400 INVALID_PARAMETERневерный параметр запроса
413 IMAGE_TOO_LARGEснимок больше пределов
415 UNSUPPORTED_IMAGEснимок не JPEG и не PNG
422 GS1_INVALID, DATA_INVALIDданные для кода не проходят проверку GS1 или не помещаются в символ
429 DAY_LIMIT, MONTH_LIMITисчерпан лимит тарифа; в ответе — usage и Retry-After
429 RATE_LIMIT, CONCURRENCY_LIMITслишком часто или слишком много одновременно; с Retry-After
503 BUSYсервер занят; с Retry-After, запрос не списан

Чего в API нет

«Честный знак» и GS1 — товарные знаки своих владельцев.