Электронный знак — API маркировки для Беларуси в формате OpenAPI 3.0 / Swagger / Bruno

А началось всё с проекта для РФ — crpt-openapi, о котором вышла статья TrueAPI — Честный знак: API для чайников в формате OpenAPI 3.0 / Swagger / Bruno. Идея простая: взять официальную документацию, прогнать через AI-агентов и получить на выходе машиночитаемую OpenAPI-спецификацию, готовые Bruno-коллекции и интерактивную документацию.

В комментариях к той статье прозвучал запрос на аналогичный проект для Электронного знака РБ

А меня ещё со времён Lineage 2 не надо дважды звать на РБ ;)

Оказалось, что в Беларуси есть своя государственная система маркировки товаров — ГИС «Электронный знак» (datamark.by). И ситуация с документацией там даже хуже, чем в РФ.

Почему Беларусь — это другой уровень сложности?

Для российского «Честного знака» у разработчика есть два источника информации:

• HTML-документация (неудобная, но кликабельная)
• PDF-документация (громоздкая, но с оглавлением)

Для белорусского «Электронного знака» — только PDF. 286 страниц сплошного текста и таблиц, версия спецификации 4.25. Никакой HTML-версии на datamark.by нет в принципе. Поиск, навигация, копирование эндпоинтов — всё вручную.

Единственный плюс — объём скромнее, чем 700-страничный талмуд для РФ. Но отсутствие даже намёка на навигацию по эндпоинтам и примерам запросов сводит этот плюс на нет.

Представьте: вам нужно интегрировать 1С с системой маркировки. Вы открываете PDF, ищете нужный раздел, и возвратно-поступательными движениями переносите это в код... Одна ошибка - и ты ошибся (с)

Как генерировалась спецификация

Шаг 1. Извлечение текста. PDF пропущен через Python-библиотеку fitz. На выходе — сырой структурированный текст со всеми эндпоинтами, параметрами и примерами.

Шаг 2. AI-генерация. Kimi K3 и swarm-агенты: набор специализированных агентов, каждый из которых отвечает за свой участок работы — один распознаёт эндпоинты, другой собирает схемы данных, третий валидирует JSON-примеры, четвёртый формирует YAML. Итеративное уточнение, множество проходов. Агенты обмениваются результатами, перекрёстно проверяют друг друга, исправляют ошибки.

Шаг 3. Визуальная проверка. Ручной вычитки как таковой не было — просто прогнал глазами результат в Swagger UI / Scalar: смотрится ли структура целостно, не потерялись ли разделы. Проверить работу API вживую не смог — нет доступа к системе: ни токена, ни аккаунта на datamark.by.

Цена вопроса: порядка 22% месячных лимитов на подписке Allegretto. Ощутимо. Но 14 758 строк YAML, покрывающих 96 операций с полной типизацией — результат, который того стоит.

Отказ от ответственности

Проект не является официальным продуктом РУП «Издательство «Белбланкавыд». Спецификация подготовлена на основе общедоступной документации и не гарантирует полноту, точность или актуальность. Используйте на свой страх и риск. Официальный источник документации по ссылке.

Я не смог проверить спецификацию на реальных запросах из-за отсутствия доступа к API (нет токена / аккаунта). Всё, что вы видите, — результат автоматизированной конвертации PDF с визуальной проверкой результата. Если найдёте неточности — пишите issue на GitHub, вместе исправим.

Как проект устроен

Всё лежит на GitHub: https://github.com/pravets/datamark.by-openapi

Структура:

openapi/
  openapi_datamark_v3.yaml  — Спецификация (96 операций, редакция 4.25)

bruno/
  datamark/                 — Bruno-коллекция (9 разделов, 96+ готовых запросов)
    environments/            — Окружения: тестовый и промышленный контуры

docs/                        — Исходники GitHub Pages
.github/workflows/           — CI/CD: валидация спецификации + автодеплой

Что покрывает спецификация

Bruno-коллекции

Каждый эндпоинт — готовый к выполнению запрос в Bruno. Два окружения:

- Тестовый контур: https://sandbox-api.datamark.by

- Промышленный контур: https://api.datamark.by

Как использовать

Способ 1: интерактивный UI (вообще без установки)

Открываете в браузере: pravets.github.io/datamark.by-openapi

GitHub Pages с рендерингом спецификации через Scalar API Reference. Все эндпоинты раскрыты в древовидном интерфейсе, схемы данных визуализированы, есть поиск. Идеально для первого знакомства с API.

Способ 2: Swagger Editor / Redoc / Scalar

Откройте файл openapi/openapi_datamark_v3.yaml в любом совместимом инструменте:
- Swagger Editor
- Redoc
- Scalar

Способ 3: Bruno (для реальной работы)

1. Установите Bruno
2. Откройте коллекцию: bruno/datamark
3. Выберите окружение (тестовый/промышленный контур)
4. Настройте токен аутентификации
5. Работайте: все 96+ запросов готовы к выполнению

Способ 4: OpenAPI Generator (для интеграции в 1С)

Сгенерируйте клиентский код на любом языке через OpenAPI Generator:

openapi-generator-cli generate \
  -i openapi/openapi_datamark_v3.yaml \
  -g <язык> \
  -o ./client

Как поучаствовать

Репозиторий: github.com/pravets/datamark.by-openapi

Так как я не имею доступа к API и не могу проверить спецификацию на реальных запросах, особенно важна обратная связь от тех, кто реально работает с «Электронным знаком»:

• Нашли неточность? — Issue
• Исправили ошибку? — Pull request
• Вопрос или предложение? — Туда же

Заключение

AI-инструменты меняют правила игры в интеграции. То, что раньше требовало недель чтения документации и ручного набивания запросов, сегодня делается swarm-агентами за несколько итераций и существенно дешевле ручной обработки.

Отсутствие HTML-документации у datamark.by делает этот проект даже более ценным, чем аналог для РФ. Там можно было хотя бы открыть браузер и пролистать. Здесь — только PDF и надежда на Ctrl+F.

Теперь у вас есть OpenAPI 3.0 спека, Bruno-коллекции с готовыми запросами и интерактивный UI. Пять минут на настройку — и вы работаете с API «Электронного знака», не открывая PDF.

Если проект оказался полезным — поставьте звёздочку на GitHub. Вопросы, предложения и правки — в комментариях и issues.