# API распознавания и создания кодов 1.0 — HTTP

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

Страница на сайте: https://libscanner.com/docs/api/1.0/

## Обзор

HTTP API на `https://api.libscanner.com`: распознавание кодов на снимке, создание DataMatrix и QR, разбор и проверка строки GS1. Внутри — те же ридеры, что продаются как библиотеки [unir](https://libscanner.com/docs/universal-reader/1.2/cpp.md) и [dmr](https://libscanner.com/docs/datamatrix-gs1/1.2/cpp.md), и тот же генератор, что [dmgen](https://libscanner.com/docs/datamatrix-generator/1.1/cpp.md).

| Метод | Что делает | Стоимость |
| --- | --- | --- |
| `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](https://libscanner.com/api).

## Ключ и вход

1. Зарегистрируйтесь на сайте и подтвердите почту — без подтверждения API отвечает 403.
2. В личном кабинете, раздел [«API»](https://libscanner.com/cabinet/api), выпустите ключ. Он показывается один раз; на сервере хранится только его хеш. Ключей может быть несколько — например, по ключу на систему; у каждого свои права: `decode` и `generate`.
3. Передавайте ключ в каждом запросе — одним из двух заголовков:

```bash
Authorization: Bearer lsk_live_…
X-API-Key: lsk_live_…
```

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

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

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

```bash
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:

```bash
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. Ровно одно из двух.

| Параметр | Значения | Смысл |
| --- | --- | --- |
| `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 |

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

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

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

```bash
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 в минуту на учётную запись.

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

```bash
{
  "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`.

```bash
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 |

```bash
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

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

```bash
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](https://api.libscanner.com/openapi.json). По ней строятся клиенты (`openapi-generator`), её понимают Postman и Insomnia, и её же читают ИИ-ассистенты. Кроме того, в Python — [вкладка Python](https://libscanner.com/docs/api/1.0/python.md) этой документации.
