Введение

Данный документ является Руководством Программиста, а так же Руководством Пользователя по использованию Программной Кассы.

В данной документации описан протокол, типы и ошибки, которые могут возникать при использовании протокола tsrv.

Данная документация будет дополняться в процессе доработок.

Сам по себе протокол взаимодействия предполагает схему “запрос-ответ”, с сообщениями в JSON формате.

На текущий момент tsrv поддерживает взаимодействие по:

• HTTP

Message

Базовой сущностью протокола (устаревший способ взаимодействия, см. HTTP) является Message. Структура Message представляет собой JSON следующего формата:

{
  "type": String,
  "address": String,
  "data": Any?,
  "headers": Map<String, String | Number | Boolean | null>
}

Поле type клиентского сообщения не обрабатывается сервером, рекомендуется передавать send.

Поле address требуется для идентификации сервиса, который будет обслуживать данное сообщение.

Поле data содержит тело запроса. Тело запроса меняется в зависимости от обслуживающего сервиса, а также исполняемой функции. Если поле не передано - используется null.

Поле headers содержит в себе дополнительную информацию, которая требуется для выполнения операции и обязано содержать поле action, в котором содержится название выполняемого метода в рамках сервиса. Числовые и логические значения заголовков преобразуются в строку, заголовки со значением null игнорируются.

Заголовок action может иметь значение с использованием любой политики наименования, например:

• getTokenBySerial
• get_token_by_serial
• GET_TOKEN_BY_SERIAL
• GetTokenBySerial

являются полностью поддерживаемыми и валидными значения вызова одного и того же метода (значение преобразуется в snake_case).

Ответ сервера имеет формат:

{
  "type": "send" | "error",
  "data": Any?
}

• send - операция выполнена успешно, в data находится результат
• error - в data находится ошибка

HTTP статус ответа всегда 200, за исключением вызова несуществующего метода - в этом случае возвращается статус 404 и ошибка http.status.404.

Важно: для уменьшения передаваемых данных следует передавать minified JSON (без переносов строк, пробелов между полями и т.п.), например:

{"type":"send","address":"ik.service.token","headers":{"action":"getTokenBySerial","token":"AVQ11031010703","tokens.refresh":"true"}}

Примеры

Валидный клиентский Message:

{
  "type": "send",
  "address": "ik.service.token",
  "headers": {
    "action": "getTokenBySerial",
    "token": "AVQ11031010703",
    "tokens.refresh": "true"
  }
}

Валидный успешный ответ сервера:

{
  "type": "send",
  "data": {
    "device_id": 131010703,
    "operator_code": 5,
    "organization": "ИП Моров А.М.",
    "pin_code_length": 5,
    "puk_code_length": 8,
    "serial": "AVQ11031010703",
    "tax_number": 191832203
  }
}

Валидный неуспешный ответ сервера:

{
  "type": "error",
  "data": {
    "name": "http.status.404",
    "description": "Ошибка запроса",
    "op_data": null
  }
}

Комментарии

Работа с комментариями

В следующих запросах могут быть переданы комментарии:

• create_sale
• create_withdraw
• create_rollback
• create_client_withdraw
• create_money_back
• create_deposit
• pay_order (в поле bundle.comments)
• bill
• close_shift, print_x_report, get_z_report_copy (см. ReportRequest)

Если комментарии переданы в запросе - они полностью заменяют комментарии из настроек (и before, и after).

Используемые типы

• Comments

Структура комментариев

В общей структуре data можно передать comments, состоящую из двух полей:

• before - комментарии, которые будут отображены перед заголовком чека
• after - комментарии, которые будут отображены после UID’a

{
  "data": {
    "sale": { ... },
    "comments": {
      "before": [],
      "after": []
    }
  }
}

Возможные типы комментариев:

• QR - QR код
• TEXT - текст
• BARCODE - код, одного из типов: EAN13, CODE128, CODE39

Значения типов и выравнивания принимаются в верхнем регистре (QR, CENTER) или с заглавной буквы (Qr, Center). Значения в нижнем регистре не поддерживаются.

Параметры:

• transient - true/false - отображать ли на электронном чеке
• align - выравнивание комментария: CENTER, LEFT, RIGHT
• size - размер QR кода. По умолчанию: 4. Рекомендуемые значения — от 1 до 16, сервисом не проверяется

QR

Параметры

• content - содержимое QR кода в base64

Пример комментария:

{
  "type": "QR",
  "content": "AA==",
  "size": 3,
  "align": "CENTER",
  "transient": false
}

TEXT

Параметры

• content - текст комментария
• dw - двойная ширина (true/false)
• dh - двойная высота (true/false)

Пример комментария

{
  "type": "TEXT",
  "content": "Hello, World!",
  "dw": false,
  "dh": false,
  "align": "CENTER",
  "transient": false
}

BARCODE

• kind - тип штрих-кода: EAN13, CODE128, CODE39
• content - содержимое штрих-кода в base64
• width - ширина штрих-кода
• height - высота штрих-кода

Пример комментария

{
  "type": "BARCODE",
  "kind": "CODE128",
  "content": "MDc5OTQzOTExMjc2Ng==",
  "width": 2,
  "height": 100,
  "align": "CENTER",
  "transient": false
}

Пример запроса продажи с комментариями

{
  "address": "ik.service.token.sales.retail",
  "headers": {
    "action": "create_sale",
    "token": "AVQ11169990665",
    "printer.dummy": "true",
    "repr.esc_pos": true
  },
  "data": {
    "sale": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "items": [
        {
          "code": {
            "gtin": "978020137962"
          },
          "price": "7.00",
          "quantity": "2.000",
          "name": "Test Flat white",
          "discount": "3.00",
          "markup": "1.00",
          "tax_rate": "tax20"
        }
      ],
      "payments": [
        {
          "payment_type": "cashless",
          "value": "12.00",
          "name": "Халва"
        }
      ],
      "cheque_discount": "0.00",
      "cheque_markup": "0.00",
      "tp_tax_number": 123456789
    },
    "comments": {
      "before": [
        {
          "type": "QR",
          "content": "AA==",
          "size": 3,
          "align": "CENTER",
          "transient": false
        },
        {
          "type": "TEXT",
          "content": "Это текст, в котором double_width и double_height и он справа",
          "dw": true,
          "dh": false,
          "align": "RIGHT",
          "transient": false
        },
        {
          "type": "TEXT",
          "content": "А это такой же текст, но он слева.",
          "dw": true,
          "dh": false,
          "align": "LEFT",
          "transient": false
        },
        {
          "type": "BARCODE",
          "kind": "EAN13",
          "content": "MDc5OTQzOTExMjc2Ng==",
          "width": 2,
          "height": 100,
          "align": "CENTER",
          "transient": false
        },
        {
          "type": "BARCODE",
          "kind": "CODE128",
          "content": "MDc5OTQzOTExMjc2Ng==",
          "width": 2,
          "height": 100,
          "align": "LEFT",
          "transient": false
        },
        {
          "type": "BARCODE",
          "kind": "CODE39",
          "content": "MDc5OTQzOTExMjc2Ng==",
          "width": 2,
          "height": 100,
          "align": "RIGHT",
          "transient": false
        }
      ],
      "after": [
        {
          "type": "TEXT",
          "content": "А это текст, который после UID'a",
          "dw": true,
          "dh": false,
          "align": "RIGHT",
          "transient": false
        }
      ]
    }
  },
  "type": "send"
}

Ошибки

В случае возникновения ошибки сервер вернёт объект следующего вида:

{
    "name": String,
    "description": String,
    "op_data": Any?
}

• при взаимодействии через /tsrv - в поле data сообщения с типом error (HTTP статус 200)
• при взаимодействии через /tsrv/{address}/{action} - в теле ответа с HTTP статусом 500 (404 - для несуществующего метода)

name - код ошибки, description - описание на русском языке, op_data - доп. данные, как правило null. Коды ошибок можно переопределить в настройках (error_mappings).

В случае возникновения ошибок на методах, отвечающих за фискализацию, ошибки, которые возникли ПОСЛЕ фискализации, помещаются в отдельное поле errors. Например, в случае возникновения ошибок с принтером, ответ будет следующего вида:

{
  "type": "send",
  "data": {
    "header": {
      "uid": "5B69B8EF9BE3E43E09894303",
      "number": 354,
      "date_time": "2025-03-01T15:01:36.933186+03:00",
      "shift_number": 78
    },
    "errors": {
      "printing": {
        "name": "rendering.io.error",
        "description": "Ошибка печати: Debug error"
      },
      "storage": null
    }
  }
}

Если в процессе возникли проблемы при работе с хранилищем данных (ФС), будет помещена так же в storage.

Стоит обратить внимание, что в случае отсутствия ошибок после фискализации поле errors не передается, либо может иметь значение null.

Коды ошибок

Ошибки СКО и ПК ($.avtpcr.*, avtpcr.*, sko.core.*, orders.* и др.) описаны в разделе Описание принципов взаимодействия. Ошибки самого tsrv:

Список поддерживаемых заголовков

Логические значения передаются как true / false. Заголовки по умолчанию можно задать в настройках (headers.defaults).

СКО

• token - серийный номер СКО
• tokens.refresh - обновление списка СКО
• renderer.sn - вывод Серийного номера СКО после QR УИ (true/false)

Выбор принтера

Подробнее — Работа с принтером.

• printer.usb.vendor, printer.usb.product - USB принтер (десятичное или 0x hex значение)
• printer.timeout - таймаут операций с USB принтером в миллисекундах. По умолчанию: 15000
• printer.spool.name - очередь печати Windows
• printer.dummy - Dummy принтер (любое значение)
• printer.dummy.error - true - Dummy принтер будет имитировать ошибку печати. По умолчанию: false
• printer.file - путь к файлу, в который будут записаны данные для печати

Отрисовка и печать чеков

• printer.spl - spl - symbols per line. Указание кол-ва символов в ширину на бумаге, на которой будет происходить печать. По умолчанию: 48, минимум: 32
• printer.cp866 - указание номера таблицы символов в принтере соответствующий кодировке CP866. По умолчанию - 17
• printer.cp1251 - указание номера таблицы символов в принтере соответствующий кодировке CP1251. Значения по умолчанию нет, используется только при передаче
• printer.feed - указание кол-во строк прокрутки бумаги после печати. По умолчанию: 5
• printer.cut - принудительное отрезание бумаги после завершения печати. По умолчанию: true
• printer.prefix - данные (base64) для отправки на принтер перед печатью чека. Может быть использовано для печати лого или изменения шрифта для последующей печати
• printer.postfix - данные (base64) для отправки на принтер после печати чека
• printer.ignore_prefix, printer.ignore_postfix - не отправлять printer.prefix / printer.postfix. Применяется только для запроса в принтер, по умолчанию для него true
• printer.code.skip - скрыть код товара на чеке. По умолчанию: false
• printer.reports.zero_payments - при установленном значении true на печатном X/Z отчёте будет всегда выводиться информация о расшифровках базовых способов оплат (Наличными, Банк. Пл. Карта)
• printer.debug - true - записывать текстовое представление чека в лог

Представление чеков

• repr.esc_pos - отдавать в объекте фискального документа дополнительный объект repr с полем esc_pos, в котором находится esc_pos (base64) представление чека
• repr.text - отдавать в объекте repr поле text - текстовое представление чека
• repr.text.b64 - отдавать в объекте repr поле text.b64 - текстовое представление чека в base64
• repr.link - отдавать в объекте repr поле link - ссылку на эл. чек
• repr.printable_lines - отдавать в объекте repr поле printable_lines - чек в виде набора строк и QR-кодов (PNG), см. FiscalResponse
• repr.text.qr_generator - способ вывода QR-кода в текстовом представлении: не указан — QR не выводится, service_plus - QR выводится в формате ServicePlus
• repr.esc_pos.qr_generator.slot - номер слота (u8) для печати QR в ESC/POS командах. По умолчанию: 48 (0x30). Обратите внимание: имя заголовка пишется именно как ecs_pos

Короткий чек (repr.custom)

Дополнительное представление короткого чека продажи: итоговая сумма, УИ и QR-код со ссылкой на эл. чек. Формируется только для документов продажи, возвращается в поле repr.custom и на принтер не отправляется.

• repr.custom.name: short - включить формирование короткого чека
• repr.custom.esc_pos, repr.custom.text, repr.custom.text_b64 - какие представления сформировать (поля esc_pos, text, text.b64 объекта repr.custom)
• repr.custom.text.qr_generator - аналог repr.text.qr_generator
• repr.custom.qr_size - размер QR-кода, от 4 до 8. По умолчанию: 8

Важно!

Печатать чеки для клиентов, отданные в repr.text, repr.link категорически запрещается, из-за отсутствия в них QR кода с УИ!

Работа с принтером

Для использования принтера требуется передать наборы заголовков, в зависимости от желаемого способа использования принтера.

Общее

Печать осуществляется путем построчного формирования для последующей печати, добавлением стилей, преобразованием в набор EscPos команд и отправкой на принтер данных.

Т.к. позиционирование построчное и основано на максимальном кол-ве символов в строке, имеется возможность передать кол-во символов для правильного формирования чека под конкретные размеры путем передачи заголовка printer.spl. Значение по умолчанию для данного заголовка - 48

Процесс вывода на печать выглядит следующим образом:

• Осуществляется подключение к печатающему устройству
• Совершается запрашиваемая операция
• Осуществляется вывод на печать сформированных данных

Заголовки принтера обязательны для всех фискальных операций, отчётов и печати копий. Если ни один принтер не указан — операция не выполняется и возвращается ошибка printers.missing.

В случае возникновения ошибки на последнем этапе (вывод на печать) операция считается успешной (документ уже фискализирован), а ошибка печати возвращается в поле errors.printing ответа.

По умолчанию данные передаются в кодировке CP866 и для корректного отображения данных на бумажном чеке, требуется, чтобы в принтере кодировкой по умолчанию была установлена кодировка CP866, либо требуется передача заголовка printer.cp866 (или printer.cp1251 для кодировки CP1251)

Принтер выбирается на основе printer.* заголовков в следующей приоритетности:

• USB
• Очередь печати Windows (только Windows)
• Dummy
• Файл

Если заголовки первого принтера не были найдены — будет попытка найти следующий принтер.

Ошибки при работе с принтером:

• printers.missing - принтер не указан
• printers.usb.invalid - неверные vendor/product USB принтера
• printers.error - принтер не найден либо ошибка его открытия

USB-принтер

Для работы с USB принтером требуется передача двух заголовков:

• printer.usb.vendor - строковое представление vendorId устройства (десятичное, либо hex с префиксом 0x)
• printer.usb.product - строковое представление productId устройства (десятичное, либо hex с префиксом 0x)

Дополнительно может быть передан printer.timeout - таймаут операций в миллисекундах (по умолчанию 15000).

На Windows, если принтер недоступен напрямую через USB, используется системный драйвер usbprint.sys.

Перед любой операцией печати с использованием USB принтера, программная касса “забирает” контроль над USB устройством. В случае если программной кассе не удалось этого сделать, будет возвращена ошибка printers.error

В случае если требуется вывести какую-то информацию на принтер до или после печати — USB устройство доступно для подключения соответственно ДО выполняемой операции и после ее завершения

Очередь печати Windows

Данный способ работает только на ОС Windows с принтерами, которые поддерживают печать через очередь печати.

Для отправки чека в очередь печати требуется передача заголовка printer.spool.name с указанием наименования принтера/очереди печати.

Dummy-принтер

Данный тип принтера не выводит ничего на печать. Для задействования требуется передача заголовка printer.dummy с любым значением

Для имитации ошибки печати можно передать printer.dummy.error: true.

Файл

Данные для печати (ESC/POS команды) записываются в файл. Для задействования требуется передача заголовка printer.file с путём к файлу. Файл перезаписывается при каждой печати, недостающие папки создаются автоматически.

Работа с СКО

Для работы с СКО не требуется дополнительных настроек.

В случае компрометации устройства, либо по решению РУП ИИЦ МНС или Оператора Программной Кассы СКО может быть заблокировано для совершения всех фискальных операций.

При попытке совершения фискальных в случаях, приведенных в абзаце выше, будет возникать ошибка avtpcr.status.blocked. В случае если статус СКО устарел (Отсутствовала синхронизация с сервером более 7 дней), будет возвращаться ошибка avtpcr.status.sync-required.

Для синхронизации с сервером требуется вызвать Обновление статуса. При первом запуске ПО и нахождении СКО требуется обязательное подключение к интернету, для получения данных об СКО и его конфигурации.

В случае если конфигурация не удалась или не завершилась (отсутствие интернета или другие причины), при попытке совершения фискальных операций будет возвращена ошибка avtpcr.not-configured. Автоматическая попытка конфигурации СКО осуществляется раз в 2 секунды. При последующих запусках, если данные не устарели и присутствуют, конфигурация может осуществляться без наличия интернета

После успешной конфигурации статус СКО автоматически обновляется с сервера раз в 15 минут, конфигурация — раз в 5 минут (при ошибке — повтор через 5 секунд). Не отправленные документы отправляются на сервер автоматически после авторизации.

Для автоматической авторизации при подключении СКО см. tokens в Настройках.

Определить состояние работы с СКО можно путем запроса Данных об СКО. Поля is_configured и is_compatible должны быть установлены в значение true, а status.block_reasons должен быть пустым

Выбор и обновление списка СКО

Список СКО определяется автоматически один раз при запуске приложения. В дальнейшем список обновляется в ручном режиме, путем передачи заголовка tokens.refresh со значением "true".

Если заголовок token не передан и подключено ровно одно СКО — будет использовано оно. Если подключено несколько СКО — будет возвращена ошибка tokens.manager.multiple.

Обновление списка так же может вести к потенциальным блокировкам и замедлению работы, т.к. происходит поиск СКО с последующей проверкой регистрационных данных СКО, которое точно так же блокирует возможность мгновенно совершить действие с СКО.

Исходя из изложенного выше, стоит передавать tokens.refresh исключительно в том случае, если СКО не было найдено, либо по какой-то причине команда отдала ошибку tokens.manager.missing

Переменные окружения

• TSRV_ADDR - адрес, который будет слушаться HTTP сервером. По умолчанию - 127.0.0.1:1828. Используется только если в настройках отсутствует секция server.

Логирование

Пример файла логгирования с ротацией по дням:

refresh_rate: 15 seconds
appenders:
  stdout:
    kind: console
  stdout_rolling:
    kind: rolling_file
    path: ./logs/log.log
    append: true
    encoder:
      pattern: "{d(%d.%m.%Y %H:%M:%S)} {({l}):5.5} {m}{n}"
    policy:
      trigger:
        kind: time
        interval: 1 day
        modulate: true
      roller:
        kind: fixed_window
        pattern: "./logs/log_{}.log"
        count: 100
        base: 1
root:
  level: info
  appenders:
    - stdout
    - stdout_rolling
# Логировать ответы и запросы
loggers:
   srv::router::with_debug:
      level: debug

Каждый запрос логируется с уникальным идентификатором и временем выполнения. Тела запросов и ответов логируются при уровне debug для srv::router::with_debug; для запросов, завершившихся ошибкой, — всегда (уровень error).

Печатные чеки в отдельный файл

Отрисованные чеки (при заголовке printer.debug: true) можно выделить в отдельный файл:

appenders:
  cheque_to_files:
    kind: rolling_file
    path: ./logs/cheque.log
    encoder:
      pattern: "{d(%d.%m.%Y %H:%M:%S)} {({l}):5.5} {m}{n}"
    policy:
      trigger:
        kind: time
        interval: 1 day
        modulate: true
      roller:
        kind: fixed_window
        pattern: "./logs/cheque_{}.log"
        count: 100
        base: 1

loggers:
  srv::services::rendering::service:
    level: info
    additive: false
    appenders:
      - cheque_to_files

Важно: В случае установки как службы, в поле path необходимо указывать абсолютный путь к файлу логирования.

Настройки:

1. Путь по умолчанию: configs/log.yaml в папке с исполняемым файлом tsrv
   • В deb пакете логи пишутся в /var/log/tsrv/
2. Путь к файлу может быть настроен с помощью аргументов при запуске ПО
   • Например: tsrv --logs-config C:/tsrv/log-config.yaml
3. Если файл не найден или содержит ошибку — логи выводятся только в консоль, уровень info

Настройки

Настройки:

• trade_point
  • information - доп. информация о торговой точке для печати
• tokens - настройки работы с СКО
  • {СЕРИЙНЫЙ_НОМЕР_СКО} - указывается серийный номер СКО
    • auto_login - true | false - флаг, для автоматической авторизации в СКО. Попытка авторизации совершается 1 раз, как только найдено СКО
    • pin_code - значение пин кода для авторизации. Требуется при указании auto_login
• headers
  • defaults - перечисление заголовком по умолчанию
• server
  • addr - указание адреса и порта, который будет слушать ПО. По умолчанию - 127.0.0.1:1828 (или значение переменной окружения TSRV_ADDR, если секция server отсутствует)
• app
  • data_dir - путь к папке с данными (используется как есть, в отличие от аргумента --data-dir, см. CLI)
• error_mappings
  • errors - словарь исходный_код: новый_код для замены кодов (name) ошибок в ответах
• renderer
  • replacements
    • {кодировка} - указывается кодировка (cp866, cp1251 и т.п.)
      • Список символов для замены
        • char - одиночный символ для замены
        • with - символ, на который заменять
  • comments - комментарии, которые будут печататься на всех док-тах продажи. В отличие от комментариев в запросе, content указывается без base64 кодирования. Если комментарии переданы в запросе - они полностью заменяют комментарии из настроек (и before, и after)
    • before - До чека
      • Список объектов
    • after - После чека
      • Список объектов
  • extra - дополнительные параметры отчётов (Extra), используются, если не переданы в запросе
• reformat_non_1_marking_quantity - (true/false) работает при указании в настройках и включении дополнительного параметра для УНП на бэкэнде. Позволяет принимать количество для маркированного весового товара не кратно 1, с пересчетом стоимости товара и отображением на печатном чеке. (в СККО уходит значение количества = 1, а цена согласно пересчета)

headers.defaults - заголовки подставляются в каждый запрос, только если не переданы в самом запросе.

Важно: если файл настроек отсутствует или содержит ошибку, используются настройки по умолчанию (ошибка пишется в лог).

Пример файла настроек:

trade_point:
  information: |
    Время работы магазина зависит только от вас:
    Пн-Пт: 10:00-20:00
    Сб-Вс: 10:00-18:00

tokens:
  AVQ11159990531:
    auto_login: true
    pin_code: 123456

headers:
  defaults:
    repr.link: true
    printer.dummy: ''
    repr.text: true

server:
  addr: 0.0.0.0:1828

error_mappings:
  errors:
    avtpcr.status.blocked: my.blocked

renderer:
  extra: ["income", "discounts", "markups", "saleItemPrepayments"]
  replacements:
    # Кодировка
    cp866:
      # char - символ, который заменять
      # with - на что заменять
      - char: '«'
        with: '"'
      - char: '»'
        with: '"'
  comments:
    before:
      - kind: text
        dw: true
        content: |
          Добро пожаловать и спасибо, что выбрали магазин "У Лукоморья"!
          С рождеством и новым годом!
    after:
      - kind: qr
        align: center
        content: 'https://www.google.com/'
        size: 5
      - kind: text
        text: |
          Скидка на бесплатный кофе!
      - kind: barcode
        content: '1234567890'
        width: 5
        height: 100
        format: code128

Установка TSRV как сервиса (службы) Windows

• Установить tsrv как сервис
  • Рядом с tsrv.exe создать файл по имени install.bat со следующим содержимым:

  cd %~dp0
  .\tsrv.exe --install-service
  pause
  

  • Запустить install.bat от администратора
• Альтернативный способ:
  • Запустить cmd.exe от Администратора
  • Выполнить c:\путь\к\tsrv.exe --install-service
• Проверить, что сервис успешно запустился:
  • sc query tsrv-native
  • В случае, если сервис не в статусе RUNNING необходимо посмотреть логи сервиса

Важно! Служба автоматически не создаёт файл настроек и конфигурации логирования.

Особенности:

• Установка требует прав администратора, путь к tsrv.exe не должен содержать пробелов
• Служба tsrv-native создаётся с автоматическим запуском и перезапуском при сбое
• Дополнительные аргументы, переданные вместе с --install-service (например, --data-dir), сохраняются в параметрах запуска службы
• При переходе ПК в спящий режим служба приостанавливается, при выходе из него — перезапускает HTTP сервер
• Команды удаления службы нет, для удаления используйте sc delete tsrv-native

Логи сервиса

• Настройка логирования сервиса находится в файле configs/log.yaml рядом с tsrv.exe, подробнее в разделе Логирование

Конфигурация сервиса

• Конфигурация сервиса находится в файле configs/settings.yaml рядом с tsrv.exe, подробнее в разделе Конфигурация

Linux

tsrv распространяется в виде deb пакета:

• исполняемый файл - /opt/tsrv/tsrv
• настройки - /opt/tsrv/configs/settings.yaml, /opt/tsrv/configs/log.yaml
• логи - /var/log/tsrv/
• данные - /opt/tsrv/tstorage

Пакет устанавливает systemd службу tsrv, которая по умолчанию выключена:

sudo systemctl enable --now tsrv

Служба перезапускается при сбое (через 10 секунд, не более 5 раз за 10 минут).

Общее описание принципов взаимодействия

Пример взаимодействия с СКО

• Получение СКО с передачей заголовка tokens.refresh со значением true, как описано в разделе Работа с СКО
• Авторизация
• Получение состояния СКО с целью проверки, открыта ли смена
  • Если смена закрыта - Открытие смены
• Внесение
• Продажа
• Аннулирование
• Возврат
• Изъятие
• Выдача
• Закрытие смены

Обработка ошибок

Ошибки разделяются на подтипы, на основании используемых префиксов, например:

• $.avtpcr.* - ошибки, которые отдаются от СКО или связаны с внутренней работой с СКО, например:
  • $.avtpcr.not_authorized - Не пройдена авторизация в СКО
  • $.avtpcr.space.insufficient - Недостаточно памяти в СКО для записи данных
• $.io.* - ошибки, связанные с передачей данных из/в СКО
• $.transport.* - ошибки, связанные с обработкой данных от СКО
• $.internal.* - ошибки, связанные с внутренними особенностями реализации протоколов взаимодействия с ПК. В случае возникновения ошибок такого рода стоит сообщать оператору
• avtpcr.* - ошибки связанные с несоблюдением требований при взаимодействии с ПК. Например:
  • avtpcr.status.blocked - Касса заблокирована
  • avtpcr.bundle.unique_id.length - Превышена макс. длина уникального идентификатора для чека
• rendering.* - ошибки, связанные с отрисовкой или печатью данных
• sko.core.receipt.* - ошибки, связанные непосредственно с функционалом ПК, который отвечает за обработку и формирование кассовых документов
• orders.* - ошибки работы с функционалом обслуживания за столиками

Command Line Interface

Usage: tsrv [OPTIONS] [COMMAND]

Commands:
  upgrade-sko    Запустить проверку и установку обновлений СКО. Требуется передача PUK кода для обновления
  analyze        Запустить анализ СКО
  change-pin     Сменить PIN код СКО
  detach-avtpcr  Перезапустить все найденные AvTPCR устройства
  help           Print this message or the help of the given subcommand(s)

Options:
      --install-service
          Установить TSRV как службу. Доступно только для Windows.
      --logs-config <LOGS_CONFIG>
          Путь к файлу с настройками логгирования. По умолчанию: '<папка tsrv>/configs/log.yaml'
      --data-dir <DATA_DIR>
          Путь к папке, в которой будут находиться данные. По умолчанию: '<папка tsrv>/tstorage'
      --settings-config <SETTINGS_CONFIG>
          Путь к файлу настроек. По умолчанию: '<папка tsrv>/configs/settings.yaml'
  -h, --help
          Print help
  -V, --version
          Print version

<папка tsrv> - папка, в которой находится исполняемый файл (не текущая рабочая директория).

При передаче --data-dir <DATA_DIR> данные хранятся в <DATA_DIR>/tstorage.

-V выводит версию сборки (совпадает с полем build версии).

upgrade-sko

tsrv upgrade-sko [--puk <PUK>] [--confirm] [--output <PATH>] [--output-encoding <ENCODING>]

• --puk - PUK код. Если не передан — будет запрошен интерактивно
• --confirm - не запрашивать подтверждение обновления
• --output - путь к файлу для записи лога обновления
• --output-encoding - кодировка файла лога (например, cp866)

analyze

tsrv analyze [--only-version]

Выводит информацию об СКО (атрибуты, регистрационные данные, конфигурацию, состояние очереди документов). Требуется, чтобы было подключено ровно одно СКО. PIN код запрашивается интерактивно.

• --only-version - вывести только версию прошивки СКО

change-pin

tsrv change-pin <PUK> <PIN>

Установка нового PIN кода СКО. Требуется, чтобы было подключено ровно одно СКО.

detach-avtpcr

Перезапуск всех найденных СКО. Доступно только для Windows.

Дополнительные возможности при фискализации

Для перечисленных ниже операций доступны доп. возможности:

• create_sale
• create_withdraw
• create_deposit
• create_rollback
• create_client_withdraw
• create_money_back
• pay_order

Уникальный ID операции (unique_id)

Имеется возможность передачи дополнительного идентификатора операции, например:

{
  "data": {
    "unique_id": "...",
    "sale": {  }
  }
}

Максимальная длина: 36 символов

Используется для поиска данных на сервере, а так же для интеграции через WebHooks на стороне АИС ПКС*

Пользовательские данные (user_data)

Имеется возможность передачи и хранения данных фронт-офиса, например:

{
  "data": {
    "user_data": "...",
    "sale": {  }
  }
}

Значение передаётся в формате base64.

Используется в случаях, если требуется сохранять доп. данные Фронт-офиса внутри СКО.

Данные хранятся внутри СКО, соответственно объем данных может повлиять на скорость фискализации.

Данные хранятся между операциями и могут быть получены посредством API вызовов.

Комментарии (comments)

См. Комментарии

Информация о торговой точке (trade_point_information)

Имеется возможность передачи и хранения информации о торговой точке, например:

{
  "data": {
    "trade_point_information": "...",
    "sale": {  }
  }
}

Данная информация печатается на чеке, если присутствует.

Важно: для create_sale, create_money_back, create_rollback и pay_order, если в настройках задано trade_point.information, будет использовано значение из настроек вместо переданного в запросе.

Данные хранятся внутри СКО, соответственно объем данных может повлиять на скорость фискализации.

Данные хранятся между операциями и могут быть получены посредством API вызовов.

Для “удаления” данных требуется передать пустую строку

Отправка на электронную почту (emails)

Имеется возможность пометки чека для отправки на почту*, например:

{
  "data": {
    "emails": [ "[email protected]" ],
    "sale": {  }
  }
}

Максимальное кол-во эмейлов - 5 штук

Данные хранятся внутри СКО, соответственно объем данных может повлиять на скорость фискализации.

Отображение маркировки в чеке (expand_marking_items)

Позволяет управлять отображением маркировки в печатном чеке, построчно, по умолчанию включено (true)

* - Функционал на стадии разработки

HTTP

Устаревший подход. Рекомендуется для всех новых интеграций использовать “Альтернативный”

Обмен сообщения происходит по адресу: host:port/tsrv

По умолчанию HTTP сервер стартует на 127.0.0.1:1828, однако это можно поменять в настройках (server.addr) или переменной окружения TSRV_ADDR

Все запросы совершаются методом POST

Заголовок Content-Type должен иметь значение application/json

Пример:

> POST /tsrv HTTP/1.1
> Host: localhost:1828
> User-Agent: insomnia/2021.5.3
> Content-Type: application/json
> Accept: */*
> Content-Length: 109

| {
|   "address": "ik.service.app",
|   "headers": {
|     "action": "version"
|   },
|   "data": null,
|   "type": "send"
| }

Альтернативный способ взаимодействия по HTTP

Возможен так же вариант взаимодействия по следующему URL: /tsrv/{address}/{action}. Метод POST поддерживается всеми функциями, часть функций (например, получение информации) так же поддерживает GET.

В данном варианте все заголовки (поле headers сообщения) могут быть помещены в заголовки HTTP запроса, а заголовок action может быть опущен, т.к. находится внутри пути запроса. В тело HTTP запроса помещается поле data сообщения.

В данном случае пример получения версии выглядит следующим образом:

> POST /tsrv/ik.service.app/version HTTP/1.1
> Host: localhost:1828
> User-Agent: insomnia/2021.5.3
> Content-Type: application/json
> Accept: */*
> Content-Length: 0

В то же время запрос на авторизацию (с телом запроса) выглядит следующим образом:

> POST /tsrv/ik.service.token.authority/authorize HTTP/1.1
> Host: localhost:1828
> User-Agent: insomnia/2021.5.3
> Content-Type: application/json
> token: AVQ11071080687
> tokens.refresh: true
> Accept: */*
> Content-Length: 19

| {
|   "pin": "47702"
| }

Требуется обратить внимание на HTTP заголовки token и tokens.refresh - они находятся в HTTP запросе

В случае ошибки возвращается HTTP статус 500 (или 404 для несуществующего метода) и ошибка в теле ответа. Пустое тело запроса эквивалентно null.

Проверки

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

Важно: перед началом проверки удаляются пробелы в начале и конце строки.

Список проверок

• Длина поля cashier не равна 0
• Длина поля cashier не превышает 20 символов

Проверка суммы

Список проверок

• value имеет не более 2 знаков после запятой
• value является положительным числом
• value не превышает максимального значения

Проверка скидки и надбавки тов. позиции

Список проверок

• discount и markup имеет не более 2 знаков после запятой
• discount и markup находится в интервале от -549755813887.99 до 549755813887.99 включительно

Проверка наименования тов. позиции

Важно: перед началом проверки удаляются пробелы в начале и конце строки.

Осуществляемые проверки

• Длина name не равна 0
• Длина name не превышает 128 символов

Проверка способов оплат и сдачи

Осуществляемые проверки

• cash + cashless + other больше, либо равно сумме К оплате по чеку
• cashless + other меньше, либо равно сумме К оплате по чеку
• cashless + other равно сумме К оплате по чеку и сумма оплат наличными равна 0. Обьяснение: если сумма наличных и безналичных платежей равна требуемой сумме к оплате, то нет возможности дать сдачу, а значит сумма наличных должна быть равна 0.
• change (сдача) должна быть больше либо равна 0

Правила округления

Все значения, имеющий тип Sum и требующие округления, округляются в 2 этапа:

• Округление до 3 знаков в сторону 0 (было: 1.2356, стало: 1.235)
• Округление до 2 знаков, по правилам математики
  • Пример 1. было: 1.235, стало: 1.24
  • Пример 2. было: 1.234, стало: 1.23

Все поля, требующие округления, описаны в соответствующих запросах, либо описании полей.

Последовательность расчетов для магазинов беспошлинной торговли:

• При добавлении товара, цена отображается в чеке в BYN;
• Предоставляется возможность оплаты в любой используемой валюте и их комбинации;
• Порядок действий после каждого внесения суммы оплаты**:
  • конвертация суммы остатка к оплате по чеку в валюту внесенной оплаты;
  • вычитание внесенной суммы из результата конвертированной суммы по чеку;
  • обратное приведение суммы остатка по чеку к базовой валюте (BYN);
  • суммы остатка к оплате и сдачи округляются до 2х знаков после запятой после каждого последующего внесения суммы;

** Если стоимость чека не закрыта действия повторяются в цикле от остатка в BYN последовательно для каждой валюты оплаты.

Формирование и передача документов для магазинов беспошлинной торговли

• Документы Продажа, Возврата и Аннулирования формируется в базовой валюте BYN:
  • В СККО и на печатном форме документы будут содержать данные, приведенные к одной валюте – BYN
• Документы Внесения и Изъятия формируются в валюте совершаемой операции:
  • В СККО и на печатной форме документы будут содержать данные о средствах в тех валютах, в которых осуществлялись кассовые операции (без приведения к одной валюте – BYN)
• Z-отчет формируется по каждой валюте отдельно:
  • Документы Продажа, Возврата и Аннулирования в СККО и на печатной форме отражаются в BYN;
  • Документы Внесения и Изъятия в СККО и на печатной форме отражаются в соответствии с валютой операции;

Сервисы

Сервисы представляют собой наборы функций, агрегированные по назначению.

Название каждого сервиса (например - app) передается в поле address клиентского сообщения. Сервер, в свою очередь, передает обработку данного сообщения “сервису”, с указанным наименованием, который в свою очередь пытается найти функцию для вызова на основании заголовка action. Стандартные сервисы, описанные в данном документе, преобразуют значение поля action в snake_case вне зависимости от переданного значения.

Напоминание: поле action может быть передано с любой политикой наименования, для сервисов, описанных в данной документации.

Важно: термин “возвращаемое значение” подразумевает под собой данные, передающиеся в поле data ответа сервера.

Все сервисы в данном разделе, которые взаимодействуют с конкретным СКО, принимают следующие заголовки:

• token - серийный номер СКО. В случае, если подключено 1 СКО и заголовок не передан - будет использовано единственное подключенное СКО
• tokens.refresh (необязательный) - "true" / "false"

ik.service.app

Данный сервис предназначен для работы с операциями управления и получения информации о приложении.

version

Вызов данной функции возвращает информацию о версии протокола приложения.

В случае выполнения данной функции, поле data отсутствует. Возвращаемое значение: Version

Примеры

Запрос:

{
  "type": "send",
  "address": "ik.service.app",
  "data": null,
  "headers": {
    "action": "version"
  }
}

Ответ

{
  "type": "send",
  "data": {
    "version": "2.0.1",
    "kind": "tsrv",
    "build": "20250225.075316"
  }
}

Работа с принтерами

ik.service.printers

• request — отправка произвольных данных на принтер

request

Метод позволяет послать данные на принтер и опционально ожидать ответа на ту или иную команду.

Входные данные: EscPosReq

Возвращаемые данные:

• Error - если произошла ошибка чтения/записи при работе с принтером
• String - base64 представление ответа, если имеется
• null - если в поле reply_size запроса отсутствует или имеет значение 0

Важно: по умолчанию заголовки printer.prefix и printer.postfix для данного метода игнорируются. Чтобы отправить их вместе с данными, требуется передать printer.ignore_prefix: false и/или printer.ignore_postfix: false (см. Заголовки).

ik.service.token

Данный сервис предназначен для получения информации об СКО.

get_tokens

Данный метод предназначен для получения информации о доступных СКО.

Данный метод не требует передачи поля data в сообщении.

Возвращаемое значение: Массив значений TokenInformation

Важно: данный метод сканирует список USB-устройств автоматически при вызове, вне зависимости от того, было ли найдено СКО или нет. После сканирования СКО попадает в список доступных к использованию.

Примеры

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "action": "get_tokens"
  }
}

Ответ:

{
  "type": "send",
  "data": [{
    "device_id": 159990531,
    "operator_code": 5,
    "organization": "ООО «АЙЭМЛЭБ»",
    "pin_code_length": 6,
    "puk_code_length": 8,
    "serial": "AVQ11159990531",
    "tax_number": 193141246,
    "is_configured": true,
    "is_compatible": true,
    "version": "1.17.643",
    "status": {
      "last_update": "2025-03-01T16:01:39.233842481+03:00",
      "block_reasons": []
    },
    "server_config": {
      "last_update": "2025-03-01T16:01:40.777846386+03:00",
      "chw_max_value": 21000,
      "trade_point": {
        "addr": "Адрес тестовой торговой точки",
        "name": "Название тестовой торговой точка"
      },
      "organization": "ООО \"АЙЭМЛЭБ\""
    }
  }]
}

get_token_by_serial

Данный метод предназначен для получения информации об СКО по серийному номеру.

Необходимость во входных данных отсутствует, однако серийный номер требуется к передаче в заголовке token. (в версии v2.x заголовок опционален, если подключено только 1 СКО)

Так же, опционально может быть передан заголовок tokens.refresh со следующими значениями:

• "true" - будет совершено обновление сканирование USB-устройств
• "false" (по умолчанию) - сканирование USB-устройств совершено не будет

Возвращаемое значение: TokenInformation

Примеры

Пример успешного выполнения

Запрос с заголовком tokens.refresh:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "action": "get_token_by_serial",
    "tokens.refresh": "true",
    "token": "AVQ11031010703"
  }
}

Ответ:

{
  "type": "send",
  "data": {
    "device_id": 159990531,
    "operator_code": 5,
    "organization": "ООО «АЙЭМЛЭБ»",
    "pin_code_length": 6,
    "puk_code_length": 8,
    "serial": "AVQ11159990531",
    "tax_number": 193141246,
    "is_configured": true,
    "is_compatible": true,
    "version": "1.17.643",
    "status": {
      "last_update": "2025-03-01T16:01:39.233842481+03:00",
      "block_reasons": []
    },
    "server_config": {
      "last_update": "2025-03-01T16:01:40.777846386+03:00",
      "chw_max_value": 21000,
      "trade_point": {
        "addr": "Адрес тестовой торговой точки",
        "name": "Название тестовой торговой точка"
      },
      "organization": "ООО \"АЙЭМЛЭБ\""
    }
  }
}

get_cash_in_token

Данный метод предназначен для получения сумм наличных в кассе.

Входные данные:

• null.
• либо строковое значение Currency

Возвращаемые данные:

• В случае, если во входных данных был передан null, будет возвращен массив значений CashIn, со всеми поддерживаемыми валютами
• В случае, если было передано значение Currency, будет возвращен массив с 1 элементом CashIn, соответствующий переданной валюте

Важно: должны быть соблюдены следующие условия: В СКО должна быть произведения авторизация по PIN-коду

Успех (все валюты)

Запрос

{
  "address": "ik.service.token",
  "headers": {
    "action": "get_cash_in_token",
    "tokens.refresh": "true",
    "token": "AVQ11169990670"
  },
  "data": null,
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": [
    {
      "cash": "352.50",
      "currency": "BYN"
    },
    {
      "cash": "0",
      "currency": "USD"
    },
    {
      "cash": "0",
      "currency": "EUR"
    },
    {
      "cash": "0",
      "currency": "RUB"
    }
  ]
}

Успех (указание валюты)

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": "BYN",
  "headers": {
    "token": "AVQ11031010703",
    "action": "get_cash_in_token"
  }
}

Ответ:

{
  "type": "send",
  "data": [
    {
      "cash": "0.00",
      "currency": "BYN"
    }
  ]
}

next_cheque_number

Данный метод предназначен для получения номера следующего документа.

Входные данные: null

Возвращаемые данные: u32 - номер следующего чека

Примеры

Успешный (пройдена авторизация)

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "action": "next_cheque_number",
    "tokens.refresh": "true",
    "token": "AVQ11031010703"
  }
}

Ответ:

{
  "type": "send",
  "data": 5782
}

get_stored_documents

Данный метод предназначен для получения информации, о количестве неотправленных записей в СКО.

На каждый документ создается 2 или более записей в СКО, кол-во документов возвращает кол-во записей, а не документов

С клиентской стороны отсутствует возможность повлиять на количество отправленных или неотправленных документов и этот метод хоть и может вводить в панику числом, отличным от 0, является лишь справочным для проверки, что документы (не)отправляются на сервер Оператора Программной Кассы.

Входные данные: null

Возвращаемые данные: u16 - количество неотправленных документов на сервер.

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "token": "AVQ11031010703",
    "tokens.refresh": "true",
    "action": "get_stored_documents"
  }
}

Ответ:

{
   "type": "send",
   "data": 100
}

Ошибка (не пройдена авторизация)

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "token": "AVQ11031010703",
    "action": "get_stored_documents",
    "tokens.refresh": "true"
  }
}

Ответ:

{
  "type": "error",
  "data": {
    "description": "сессия не авторизована (команда требует обязательной авторизации)",
    "name": "$.avtpcr.not_authorized",
    "op_data": null
  }
}

get_oldest_document

Данный метод предназначен для получения самого “старого” неотправленного документа на сервер Оператора Программной Кассы.

Входные данные: null

Возвращаемые данные: OldestDocument

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token",
  "data": null,
  "headers": {
    "token": "AVQ11031010703",
    "action": "get_oldest_document",
    "tokens.refresh": "true"
  }
}

Ответ:

{
  "type": "send",
  "data": {
    "date": "2021-09-13T10:17:35+03:00",
    "uid": "A50B7A727894C03707CF108F"
  }
}

get_token_state

Данный метод позволяет получить сохраненную информацию об СКО.

Входные данные: отсутствуют

Возвращаемые данные:

• State, если авторизация пройдена
• ошибка $.avtpcr.not_authorized, если авторизация не пройдена

update_status

Принудительное обновление статуса СКО.

Входные данные: отсутствуют

Возвращаемые данные: UpdateStatus

get_total_income

Входные данные: Currency

Возвращаемые данные: Sum

get_status

Получение статуса СКО.

Статус unknown означает то, что приложение не смогло узнать статус кассы.

Статус blocked означает, что касса была заблокирована.

Статус active означает, что все хорошо и касса может работать.

Входные данные: отсутствуют

Возвращаемые данные: Status

print_prev_receipt

Получение и печать ранее фискализированного документа.

Входные данные: ReceiptRequest

Возвращаемые данные:

• FiscalResponse (без поля errors) - если чек найден
• ошибка tsrv.storage.entry-not-found - если чек не найден

Важно: Данный метод требует авторизации в СКО.

Важно: если data.shift_number передано значение null требуется наличие открытой смены

Важно: для данного запроса требуются заголовки для работы с принтером

Пример запрос:

{
    "address": "ik.service.token",
    "headers": {
        "action": "print_prev_receipt",
        "printer.usb.vendor": "0x0471",
        "printer.usb.product": "0x0055",
        "printer.feed": "2",
        "tokens.refresh": "true",
        "printer.debug": true
    },
    "type": "send",
    "data": {
        "shift_number": 59,
        "number": 242
    }
}

Ответ (успех)

{
  "type": "send",
  "data": {
    "repr": {
      "text": "Добро пожаловать и спасибо, что выбрали магазин \n\"У Андрея Кирилловича\"!                           \nС рождеством и новым годом!                     \n                 ООО \"АйЭмЛэб\"                  \n                  Офис Скорины                  \n       г. Минск УЛ. СКОРИНЫ ФРАНЦИСКА, 8        \n  Время работы магазина зависит только от вас:  \n                Пн-Пт: 10:00-20:00              \n                Сб-Вс: 10:00-18:00              \nУНП 193141246                  РН СККО 119026738\n        Не является платежным документом        \n               Документ внесения                \n                   N док. 343                   \n------------------------------------------------\nСумма:                                    100.00\n------------------------------------------------\nКассир: Test                 04.11.2025 17:55:55\n          УИ D756D6D53709586B07183432           \n          Скидка % на бесплатный кофе!          \n\n",
      "link": "https://receipts.cloud.stage.imlab.by/render/D756D6D53709586B07183432"
    },
    "unique_id": "123774",
    "header": {
      "uid": "D756D6D53709586B07183432",
      "number": 343,
      "date_time": "2025-11-04T17:55:55.352882+03:00",
      "shift_number": 104
    }
  }
}

repr_prev_receipt

Получение представления ранее фискализированного документа без печати.

Работает аналогично print_prev_receipt, но не требует заголовков принтера. Требуемые представления указываются заголовками repr.* (см. Заголовки).

Входные данные: ReceiptRequest

Возвращаемые данные:

• FiscalResponse (без поля errors) - если чек найден
• ошибка tsrv.storage.entry-not-found - если чек не найден

get_minmax_receipts

Получение информации о первом и последнем известном документе в рамках текущей смены.

Входные данные: отсутствуют (тело запроса игнорируется)

Возвращаемые данные:

• MinMaxReceipts - в случае успеха
• null - если в текущей смене нет документов
• ошибка $.avtpcr.shift.closed - если смена закрыта
• ошибка $.avtpcr.not_authorized - если не пройдена авторизация в СКО

set_trade_point_information

Входные данные:

{
   "content": "TradePointInformation"
}

• TradePointInformation - указывается режим работы торгового объекта, контактные данные (телефон) и другое

Передача "content": null удаляет ранее установленную информацию.

Возвращаемые данные: null

get_certificate

Получение сертификата СКО.

Входные данные: отсутствуют

Возвращаемые данные: String - сертификат в base64 формате.

Срок действия сертификата можно узнать из поля cert_eol TokenInformation.

render_non_fiscal_header

Получение текстового представления заголовка чека (наименование и УНП организации, торговая точка, доп. информация о торговой точке, рег. и серийный номер ПК). Может использоваться для печати нефискальных документов.

Входные данные: отсутствуют

Учитывает заголовки отрисовки (printer.spl и т.п.).

Возвращаемые данные:

{
  "value": String
}

ik.service.token.firmware

Добавлены эндпоинты для обновления прошивки СКО.

⚠️Важно! Этот процесс достаточно чувствительный к питанию СКО

⚠️При отключении питания СКО может стать неисправно

⚠️Процесс может занять до нескольких минут времени. Ответ на запрос будет выдан только по завершении обновления.

⚠️После завершения обновления СКО “переподключается”, соответственно без передачи заголовка tokens.refresh со значением true будет не найдено.

Проверить совместимость tsrv c версией СКО можно следующим образом:

1. Запросить информацию об СКО: Получение СКО
2. В ответе извлечь поле is_compatible. В случае, если версия ПО несовместима с версией прошивки СКО, значение будет равно false

Перед обновлением стоит убедиться, что прошивка доступна: 1.

{
   "address": "ik.service.token.firmware",
   "headers": {
      "action": "check",
   },
   "data": null,
   "type": "send"
}

Ответ следующего формата:

{
   "type": "send",
   "data": {
      "version": "1.17" <--- или `null`, если прошивка отсутствует
   }
}

В случае, если is_compatible == false и в ответе на наличие обновления прошивки пришел null в поле version, следует обратиться в соответствующий интеграционный чат с предоставлением информации о рег. номере и серийном номере СКО.

Процесс обновления прошивки через эндпоинты выглядит следующим образом:

1. Требуется авторизация по PUK коду:

{
   "address": "ik.service.token.authority",
   "headers": {
      "action": "authorize",
      "tokens.refresh": true
   },
   "type": "send",
   "data": {
      "puk": "12345678"
   }
}

⚠️Если авторизация по пин-коду была пройдена, требуется сделать logout

2. Выполнить запрос на обновление прошивки:

{
   "address": "ik.service.token.firmware",
   "headers": {
      "action": "upgrade",
      "tokens.refresh": "true"
   },
   "data": null,
   "type": "send"
}

В ответ будет отдан ответ в формате:

{
   "type": "send",
   "data": {
      "version": "1.17" <--- Либо null, если обновление не найдено
   }
}

⚠️ Этот этап может занять существенно времени в зависимости от ряда условий: интернет соединение, скорость и стабильность USB порта. Важно, что на этом этапе отключение tsrv, перезапуск ПК или отключение СКО в том числе из-за сбоя питания недопустимо и может привести к полной неисправности СКО

3. После получения ответа СКО будет переподключено и можно выполнить авторизацию по пин-коду. При авторизации рекомендуется передать tokens.refresh со значением true для поиска СКО среди USB устройств

ik.service.token.authority

Данный сервис предназначен для совершения операций с СКО - связанных с PIN/PUK кодами.

authorize

Данный метод предназначен для совершения авторизации в СКО.

Входные данные: Pin

Возвращаемые данные:

• null в случае успеха.

Важно: после каждой неверной попытки авторизации задержка ответа увеличивается. После 3 попытки время ожидания ответа авторизации составляет 10 секунд. После ввода успешного PIN-кода задержка сбрасывается.

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "data": {
    "pin": "16522"
  },
  "headers": {
    "tokens.refresh": "true",
    "token": "AVQ11031010703",
    "action": "authorize"
  }
}

Ответ:

{
  "type": "send",
  "data": null
}

logout

Данный метод предназначен для совершения выхода из авторизованной сессии.

Входные данные: null

Возвращаемые данные:

• null в случае успеха

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "data": null,
  "headers": {
    "tokens.refresh": "true",
    "token": "AVQ11031010703",
    "action": "logout"
  }
}

Ответ:

{
  "type": "send",
  "data": null
}

ik.service.token.shift

Данный сервис предназначен для работы со сменой.

open_shift

Данный метод предназначен для открытия смены.

Входные данные: OpenShiftRequest

{
  "mode": "default" | "restaurant" | "gas" | { "dfs": ModeDfs } | null
}

• mode - Необязательный параметр. По умолчанию — ретейл. Подробнее — OpenShiftRequest

Возвращаемые данные:

• null в случае успеха.

Важно: смена может быть открыта не более 24 часов.

Примеры

Успех

Запрос:

{
  "address": "ik.service.token.shift",
  "headers": {
    "action": "open_shift"
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": null
}

get_x_report

Данный метод предназначен для получения X-отчета.

Входные данные: null

Возвращаемые данные:

• Report в случае успеха

Важно: данный метод НЕ отдает документ на печать. Для отправки на печать следует использовать метод печати X-отчёта

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token.shift",
  "data": null,
  "headers": {
    "action": "get_x_report",
    "token": "AVQ11169990670",
    "tokens.refresh": "true"
  }
}

print_x_report

Данный метод предназначен для получения X-отчета.

Входные данные: ReportRequest или null

Важно: для печати требуется передача заголовков для работы с принтером

Возвращаемые данные:

• Report в случае успеха

Важно: в случае, если в смене не совершалось никаких операций, счетчики (data.currency_counters) будут пустыми, однако на печать в любом случае уйдут счетчики с нулевыми значениями по валюте BYN

Примеры

Примеры аналогичны получению Х-отчета, за исключением необходимых заголовков для работы с принтером

close_shift

Данный метод предназначен для закрытия смены с последующим получением Z-отчета.

Входные данные:

• null или ReportRequest

Возвращаемые данные:

• Report в случае успеха.

Важно: для закрытия смены, требуется полное изъятие наличных.

Примеры

Успех

Запрос:

{
  "address": "ik.service.token.shift",
  "headers": {
    "action": "close_shift",
    "token": "AVQ11169990670",
    "printer.dummy": ""
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "close_date": "2024-07-18T21:06:21+03:00",
    "company_name": "ООО \"АЙЭМЛЭБ\"",
    "currency_counters": {
      "BYN": {
        "additional": {
          "third_party": {
            "rollback": {
              "count": 1,
              "sum": "5.00"
            },
            "total": {
              "count": 10,
              "sum": "104.00"
            }
          }
        },
        "client_withdraws": {
          "count": 1,
          "sum": "1.00"
        },
        "deposits": {
          "count": 4,
          "sum": "310.00"
        },
        "marking_si": {
          "count": 0,
          "sum": "0.00"
        },
        "marking_ukz": {
          "count": 0,
          "sum": "0.00"
        },
        "money_backs": {
          "card": "0.50",
          "cash": "0.50",
          "count": 1,
          "other": "0.00",
          "sum": "1.00"
        },
        "rollbacks": {
          "card": "6.00",
          "cash": "0.00",
          "count": 1,
          "other": "0.00",
          "sum": "6.00"
        },
        "sales": {
          "card": "60.00",
          "cash": "44.00",
          "count": 10,
          "other": "0.00",
          "sum": "104.00"
        },
        "si_refund": {
          "count": 0,
          "sum": "0.00"
        },
        "si_rollback": {
          "count": 0,
          "sum": "0.00"
        },
        "ukz_refund": {
          "count": 0,
          "sum": "0.00"
        },
        "ukz_rollback": {
          "count": 0,
          "sum": "0.00"
        },
        "withdraws": {
          "count": 1,
          "sum": "352.50"
        }
      }
    },
    "first_sale_number": 19,
    "last_sale_number": 35,
    "number": 3,
    "open_date": "2024-07-18T17:07:22+03:00",
    "sales_count": 10,
    "tax_number": 193141246,
    "total_income": {
      "BYN": "149.00"
    },
    "shift_mode": 0,
    "uid": "D5CCDF029529C4E606A6E41E"
  }
}

get_z_report_copy

Данный метод предназначен для печати копии Z-отчета.

Входные данные: null или ReportRequest

Возвращаемые данные:

• Report в случае успеха.
• Repr Результаты отрисовки чека и прочие доп. данные (при наличии)

Важно: требуется авторизация

Важно: для печати требуется передача заголовков для работы с принтером

Важно: : Метод доступен только в закрытой смене и отдает информацию только о последней закрытой смене

rates

Получение курсов валют, установленных при открытии смены в режиме МБТ.

Входные данные: отсутствуют

Возвращаемые данные: Rates

{
  "type": "send",
  "data": {
    "USD": { "sum": 32512, "per": 1 }
  }
}

ik.service.token.deposit

create_deposit

Входные данные: NewSumChequeRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов

Примеры запросов

Успех

Запрос:

{
  "address": "ik.service.token.deposit",
  "headers": {
    "action": "create_deposit",
    "token": "AVQ11031010703",
    "printer.dummy": ""
  },
  "data": {
    "sum_cheque_data": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "sum": "1.00"
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "repr": {
      "link": "https://receipts.cloud.stage.imlab.by/render/78E24333F1D9399507183432"
    },
    "header": {
      "uid": "78E24333F1D9399507183432",
      "number": 359,
      "date_time": "2025-11-05T17:23:12.498732+03:00",
      "shift_number": 112
    },
    "errors": null
  }
}

ik.service.token.withdraw

create_withdraw

Входные данные: NewSumChequeRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов, либо сумма изъятия должна быть на сумму всех наличных в кассе по указанной валюте

Примеры запросов

Успех

Запрос:

{
  "address": "ik.service.token.withdraw",
  "headers": {
    "action": "create_withdraw",
    "token": "AVQ11169990670",
    "printer.dummy": ""
  },
  "data": {
    "sum_cheque_data": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "sum": "352.50"
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "header": {
      "uid": "EEBAE74068406C4509894303",
      "number": 362,
      "date_time": "2025-03-01T18:54:35.761641+03:00",
      "shift_number": 78
    },
    "errors": null
  }
}

create_client_withdraw

Входные данные: NewSumChequeRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Сумма выдачи в рамках одной операции ограничена законодательно, не должна превышать 5 базовых величин

Важно: Доступная валюта для операции выдачи BYN

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов

Примеры запросов

Успех

Запрос:

{
  "address": "ik.service.token.withdraw",
  "headers": {
    "action": "create_client_withdraw",
    "token": "AVQ11031010703",
    "printer.dummy": ""
  },
  "data": {
    "sum_cheque_data": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "sum": "1.00"
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "header": {
      "uid": "598813A9ECD7CB4B09894303",
      "number": 356,
      "date_time": "2025-03-01T17:25:14.490005+03:00",
      "shift_number": 78
    },
    "errors": null
  }
}

ik.service.token.sales.retail

create_sale

Данный метод предназначен для совершения операции продажи.

Входные данные: SaleRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов

Примеры

Успех

Запрос:

{
  "address": "ik.service.token.sales.retail",
  "headers": {
    "action": "create_sale",
    "token": "AVQ11169990670",
    "printer.dummy": ""
  },
  "data": {
    "sale": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "items": [
        {
          "section": {
            "code": 1,
            "name": "Тестовая секция"
          },
          "code": {
            "code": "1845678901001"
          },
          "price": "7.00",
          "quantity": "1.000",
          "name": "Test Flat white",
          "discount": "1.00",
          "markup": "1.00",
          "tax_rate": "tax20"
        },
        {
          "code": {
            "code": "123132"
          },
          "price": "10.00",
          "quantity": "1.000",
          "name": "Не gtin товар",
          "discount": "1.00",
          "markup": "2.00",
          "tax_rate": "tax10"
        }
      ],
      "payments": [
        {
          "payment_type": "cashless",
          "value": "6.00",
          "name": "Халва"
        },
        {
          "payment_type": "cash",
          "value": "20.00"
        }
      ],
      "cheque_discount": "2.00",
      "cheque_markup": "1.00",
      "tp_tax_number": 123456789
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "repr": {
      "link": "https://receipts.cloud.stage.imlab.by/render/60061721731D714C07183432"
    },
    "header": {
      "uid": "60061721731D714C07183432",
      "number": 344,
      "date_time": "2025-11-04T18:25:31.139989+03:00",
      "shift_number": 104
    },
    "errors": null
  }
}

ik.service.token.moneyback

create_money_back

Операция возврата.

Входные данные: NewMoneyBackRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов

Важно: Кол-во наличных в кассе по указанной валюте должно быть больше, либо равно сумме возврата наличными средствами

Примеры

Успех

Запрос:

{
  "address": "ik.service.token.moneyback",
  "headers": {
    "action": "create_money_back",
    "token": "AVQ11169990670",
    "printer.dummy": ""
  },
  "data": {
    "money_back": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "items": [
        {
          "section": {
            "code": 1,
            "name": "Тестовая секция"
          },
          "code": {
            "scan": [
              {
                "gtin": "123456789012"
              },
              {
                "unknown": "j239ej2je"
              },
              {
                "ukz": "midom0im20m03223d-2-d"
              }
            ]
          },
          "price": "7.00",
          "quantity": "1.000",
          "name": "Test Flat white",
          "markup": "1.50",
          "discount": "2.20"
        },
        {
          "code": {
            "service": "121"
          },
          "price": "10.00",
          "quantity": "1.000",
          "name": "Не gtin товар",
          "markup": "1.10",
          "discount": "2.40"
        }
      ],
      "payments": [
        {
          "payment_type": "cash",
          "value": "10"
        },
        {
          "payment_type": "cashless",
          "value": "5"
        }
      ]
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "header": {
      "uid": "20DDAEBDBD0A31E309894303",
      "number": 357,
      "date_time": "2025-03-01T17:40:45.794886+03:00",
      "shift_number": 78
    },
    "errors": null
  }
}

ik.service.token.rollback

create_rollback

Операция аннулирования

Входные данные: NewRollbackRequest

Возвращаемые данные: FiscalResponse

Важно: Для совершения данной операции требуется Авторизация в СКО

Важно: Для совершения данной операции требуется открытая смена

Важно: Для совершения данной операции смена должна быть открыта менее 24 часов

Важно: данная операция требует того, чтобы аннулируемый документ находился в текущей смене, а так же того, что чек не был аннулирован ранее

Важно: Для данного запроса поле currency игнорируется и может быть не передано

Важно: Доступно аннулирование только последнего документа, если он является документом продажи

Важно: Дополнительно можно передать поле rollback.target_num с указанием номера аннулируемого док-та продажи. Если переданный номер не совпадает с последним док-том продажи будет возвращена ошибка.

Примеры

Успех

Запрос:

{
  "address": "ik.service.token.rollback",
  "headers": {
    "action": "create_rollback",
    "token": "AVQ11031010703",
    "printer.dummy": ""
  },
  "data": {
    "rollback": {
      "header": {
        "cashier": "Кассир"
      }
    }
  },
  "type": "send"
}

Ответ:

{
  "type": "send",
  "data": {
    "header": {
      "uid": "F9BC5D1B0A3D061709894303",
      "number": 359,
      "date_time": "2025-03-01T17:50:25.365454+03:00",
      "shift_number": 78
    },
    "errors": null
  }
}

Ресторанный режим

1

create_or_edit_order

Работа с любым заказом начинается с его создания, а создание сопровождается редактированием.

1. В СКО записывается краткая информация о заказе - Сумма + Номер счёта, если имеется
2. Если для заказа был распечатан счёт и вызван метод редактирования этого заказа, номер счёта будет сброшен
3. При редактировании заказа, изменение суммы заказа влечет за собой увеличение счётчиков “Коррекции” или “Сумма оформленных заказов”
4. Если заказ не был закрыт / отменен / оплачен, на момент закрытия смены он увеличивает счётчики “Перемещенных” заказов
5. Детальная информация о заказе хранится на ФС. В случае ее повреждения и/или несоответствия данным в СКО требуется повторно вызвать этот метод. Если заказ существует в СКО и его сумма совпадает с известной - увеличения счётчиков не произойдет

Взаимодействие

Входные данные:

Ответ:

Пример запроса:

{
  "address": "ik.service.token.orders",
  "type": "send",
  "headers": {
    "action": "create_or_edit_order"
  },
  "data": {
    "id": "test_id",
    "cashier": "test",
    "table": 1,
    "items": [
      {
        "code": {
          "code": "1059429"
        },
        "price": "10.99",
        "quantity": "1.000",
        "name": "Вазелин"
      }
    ]
  }
}

Пример успешного запроса:

{
  "type": "send",
  "data": {
    "errors": null
  }
}

cancel_order

Отмена заказа

Данные

Входные данные:

{
  "id": "string"
}

В поле id передается идентификатор заказа, влияет на счетчик “Отмененных заказов”

Возвращаемые:

get_orders_information

Получение информации о заказе, хранящейся в СКО

Входные данные: Отсутствуют

Ответ:

{
  "orders": {
    "test_id": {
      "sum": "10.99",
      "bill_number": null,
      "prepayment_sum": 500
    }
  }
}

Orders

OrderInformation

get_order_information_by_id

Получение информации об одном заказе, хранящейся в СКО.

Входные данные: String - ID заказа (тело запроса — JSON строка, например "test_id")

Возвращаемые данные:

• OrderInformation — если заказ найден
• null - если заказ не найден

pay_order

Данные

Входные:

Bundle

Возвращаемые данные: FiscalResponse.

Несколько способов оплаты cash объединяются в один перед фискализацией.

Пример запроса:

{
  "address": "ik.service.token.orders",
  "type": "send",
  "headers": {
    "action": "pay_order",
    "printer.cut": false,
    "printer.feed": 0,
    "printer.dummy": "true"
  },
  "data": {
    "order_id": "test_id",
    "cashier": "test",
    "payments": [
      {
        "payment_type": "cash",
        "value": "10.99"
      }
    ]
  }
}

bill

Печать счёта.

Для корректной печати требуется передача заголовков для работы с принтером

Входные данные:

{
  "id": "string",
  "comments": Comments?
}

В поле id передается идентификатор заказа для печати счёта

Используемые типы

• Comments

Ответ:

{
  "type": "send",
  "data": {
    "number": 43,
    "errors": null
  }
}

• number - сформированный / присвоенный номер счёта

Типы данных

Errors

Error

Тип extra

Дополнительные блоки печатного X/Z-отчёта. Влияют только на печать и представления (repr), но не на JSON ответа.

[
"income", "discounts", "markups", "saleItemPrepayments", "cleanPayments"
]

Описание полей

• income - накопленный оборот
• discounts - скидки
• markups - надбавки
• saleItemPrepayments - авансовые платежи
• cleanPayments - “чистые” суммы по способам оплаты: продажи за вычетом возвратов и аннулирований (наличными, банк. пл. картой, иными способами с расшифровкой)

Если extra не передано в запросе — используется значение renderer.extra из настроек.

Важно: Для отображения данных в расширенном отчете типа cleanPayments требуется указывать group.key и group.name у типа Payment при осуществлении продаж и возвратов.

Тип Version

{
  "version": "2.0.1",
  "kind": "tsrv",
  "build": "20250225.075316"
}

• version - Версия ПК
• kind - Тип ПК: tsrv, smartx или unknown
• build - Версия сборки API-слоя (tsrv), совпадает с выводом tsrv -V

Поле version отдается в формате SemVer.

Результат выполнения фискальной операции

{
  "repr": Repr?,
  "unique_id": String?,
  "header": {
    "uid": String,
    "number": Int,
    "date_time": String,
    "shift_number": Integer
  },
  "errors": Errors?
}

Поля:

Repr

Поле repr отсутствует, если ни одно из представлений не запрошено.

PrintableLine

Текстовый блок:

{ "type": "text", "value": [ String ] }

QR-код:

{
  "type": "qr",
  "value": {
    "value": String,               // PNG изображение в base64
    "alignment": "left" | "center" | "right",
    "kind": "uid" | "other"        // uid - QR с УИ чека
  }
}

Тип ReportRequest

Используется в close_shift, print_x_report и get_z_report_copy.

{
  "comments": Comments?,
  "extra": Extra?,
  "trade_point_information": String?
}

Описание полей

• comments - Comments
• extra - Extra. Если не передано - используется значение renderer.extra из настроек
• trade_point_information - доп. информация о торговой точке для печати

Тип Sum

Данный тип представляет собой значение, с плавающей точкой, представленное в строковом виде.

В случае, если данное значение фигурирует во входных данных, оно обязано содержать 2 знака после запятой (иметь формат X.XX), даже если последние равны 0 (например: 12345.00)

На данный тип наложен ряд ограничений:

1. Максимальное значение: 549755813887.99
2. Минимальное значение: -549755813887.99

Данные ограничения продиктованы ограничениями протокола СККО.

Пример валидного значения Sum:

"12345.67"

Тип UID

Данный тип представляет собой строковое значение в HEX формате Уникального Идентификатора (УИ) кассового документа

Пример значения:

"8914D11E9BA4471D0A327BFB"

Тип DateTime

Данный тип представляет собой дату и время в строковом формате. В зависимости от выполняемого метода и данных может содержать или не содержать информацию о миллисекундах, однако обязательно содержит информацию о часовом поясе.

Примеры:

С миллисекундами:

"2021-09-13T10:17:35.123+03:00"

Без миллисекунд:

"2021-09-13T10:17:35+03:00"

Тип Currency

Возможные значения:

enum варианты значения*:

• BYN

• USD

• RUB

• EUR

• список значений расширяется в зависимости от настроек сервера

Пример:

"BYN"

Тип TokenInformation

{
   serial: String,
   device_id: u32,
   organization: String,
   tax_number: u32,
   pin_code_length: u32,
   puk_code_length: u32,
   operator_code: u32,
   is_configured: bool,
   is_compatible: bool,
   version: String,
   status: TokenStatus?,
   server_config: ServerConfig?,
   cert_eol: DateTime
}

• serial - серийный номер СКО
• device_id - Регистрационный номер ПК в СККО
• organization - наименование компании, на которую зарегистрировано СКО
• tax_number - УНП СХ
• pin_code_length - длина PIN-кода требуемого для авторизации
• puk_code_length - длина PUK-кода требуемого для авторизации
• operator_code - код Оператора Программной Кассы в соответствии с реестром
• is_configured - СКО сконфигурировано (см. Работа с СКО)
• is_compatible - версия прошивки СКО совместима с ПО
• version - версия прошивки СКО
• status - статус СКО:
  • last_update - DateTime? — время последнего обновления статуса
  • block_reasons - массив String — причины блокировки (пустой, если СКО не заблокировано)
• server_config - конфигурация, полученная с сервера:
  • last_update - DateTime? — время последнего обновления
  • chw_max_value - u64 — максимальная сумма выдачи
  • trade_point - { "addr": String, "name": String }? - торговая точка
  • organization - String — наименование организации
• cert_eol - Дата-время окончания срока действия сертификата СКО

Пример:

{
  "type": "send",
  "data": [
    {
      "device_id": 119026738,
      "operator_code": 910000001,
      "organization": "Общество с ограниченной ответственностью \"АЙЭМЛЭБ\"",
      "pin_code_length": 6,
      "puk_code_length": 8,
      "serial": "AVQ11159990839",
      "tax_number": 193141246,
      "is_configured": true,
      "is_compatible": true,
      "version": "1.17.643",
      "status": {
        "last_update": "2025-11-05T18:46:09.192369818+03:00",
        "block_reasons": []
      },
      "server_config": {
        "last_update": "2025-11-05T18:48:10.816893147+03:00",
        "chw_max_value": 21000,
        "trade_point": {
          "addr": "г. Минск УЛ. СКОРИНЫ ФРАНЦИСКА, 8",
          "name": "Офис Скорины"
        },
        "organization": "ООО \"АйЭмЛэб\""
      },
      "cert_eol": "2030-11-05T00:00:00Z"
    }
  ]
}

Тип CashIn

{
  "currency": Currency,
  "cash": Sum
}

Используемые типы:

• Currency
• Sum

Пример:

{
  "cash": "25.46",
  "currency": "BYN"
}

Тип OldestDocument

{
  "uid": UID,
  "date" DateTime
}

Используемые типы:

• UID
• DateTime

Пример:

{
  "uid": "A50B7A727894C03707CF108F",
  "date": "2021-09-13T10:17:35+03:00"
}

Тип Pin

{
  "pin": String
}

• pin - строковое представление PIN-кода

Вместо pin может быть передан puk - для авторизации по PUK-коду (требуется, например, для обновления прошивки):

{
  "puk": "12345678"
}

Пример:

{
  "pin": "16522"
}

Тип MinMaxReceipts

{
  min: u32,
  max: u32
}

Описание полей

• min - номер первого документа в смене
• max - номер последнего документа в смене

Пример

{
  "min": 5981,
  "max": 5981
}

Тип ReceiptRequest

{
  shift_number: u16?,
  number: u32
}

Описание полей

• shift_number - опциональное поле номера смены, если не указано используется текущий номер смены
• number - номер фискального документа в указанной/текущей смене

Пример

{
   "shift_number": null, 
   "number": 5981
}

Тип Comments

"comments": {
    "before": [ *Comment ]?,
    "after": [ *Comment ]?,
}

Описание полей

before - не обязательное поле, комментарии до заголовка чека

after - не обязательное поле, комментарии после UID чека

Используемые типы

• Comment

Тип Comment

{
    "type:" CommentType,
    "content": String,
    "kind": CodeType?,
    "width": u8?,
    "height": u8?,
    "size": u8?,
    "align": Align?
}

Описание полей

type - тип комментария, может принимать значения: QR, TEXT, BARCODE

content - содержание комментария. В случае TEXT - utf-8 строка, в случае QR или BARCODE - base64 строка

kind - тип кода, может принимать значения: CODE128, EAN13, CODE39. Передается только, если type - BARCODE

size - размер QR-кода, передается только, если type - QR

width - ширина штрихкода, передается только, если type - BARCODE

height - высота штрихкода, передается только, если type - BARCODE

align - выравнивание, может принимать значения: LEFT, CENTER, RIGHT

Тип EscPosReq

{
  "b64_content": String,
  "reply_size": usize?
}

Описание полей

• b64_content - EscPos команды в формате base64
• reply_size - размер ожидаемого ответа. Если ответ не требуется, размер - 0, если значение данного поля null, то значением по умолчанию является 0

Тип Report

{
  uid: UID?,
  device_id: u32,
  tax_number: u32,
  company_name: String,
  open_date: DateTime,
  close_date: DateTime?,
  number: u16,
  first_sale_number: u32,
  last_sale_number: u32,
  sales_count: u16,
  total_income: Map<Currency, Sum>,
  currency_counters: Map<Currency, ReportCounter>,
  shift_mode: i32
}

• uid - УИ. В случае, если это Z-отчет - обязательное поле
• device_id - Регистрационный номер ПК в СККО
• tax_number - УНП
• company_name - Наименование организации
• open_date - Дата-время открытия смены
• close_date - Дата-время закрытия смены, присутствует только в Z-отчете
• number - Номер смены
• first_sale_number - Номер первого документа продажи в смене
• last_sale_number - Номер последнего документа продажи в смене
• sales_count - количество документов продаж
• total_income - накопленный оборот по валютам
• currency_counters - сменные счетчики по каждой валюте, по которой совершались операции в смене
• shift_mode - числовой код режима смены

В ответах X/Z-отчётов (get_x_report, close_shift и т.п.) дополнительно может присутствовать поле repr (см. FiscalResponse), если запрошено представление.

Используемые типы:

• ReportCounter

Пример (сокращён):

{
  "type": "send",
  "data": {
    "close_date": "2024-07-18T11:17:03+03:00",
    "company_name": "ООО \"АЙЭМЛЭБ\"",
    "currency_counters": {
      "BYN": {
        "additional": {
          "third_party": {
            "rollback": {
              "count": 1,
              "sum": "6.00"
            },
            "total": {
              "count": 1,
              "sum": "6.00"
            }
          }
        },
        "client_withdraws": {
          "count": 1,
          "sum": "1.00"
        },
        "deposits": {
          "count": 1,
          "sum": "10.00"
        },
        "marking_si": {
          "count": 0,
          "sum": "0.00"
        },
        "marking_ukz": {
          "count": 0,
          "sum": "0.00"
        },
        "money_backs": {
          "card": "0.50",
          "cash": "0.50",
          "count": 1,
          "other": "0.00",
          "sum": "1.00"
        },
        "rollbacks": {
          "card": "6.00",
          "cash": "0.00",
          "count": 1,
          "other": "0.00",
          "sum": "6.00"
        },
        "sales": {
          "card": "45.00",
          "cash": "0.00",
          "count": 10,
          "other": "0.00",
          "sum": "45.00"
        },
        "si_refund": {
          "count": 0,
          "sum": "0.00"
        },
        "si_rollback": {
          "count": 0,
          "sum": "0.00"
        },
        "ukz_refund": {
          "count": 0,
          "sum": "0.00"
        },
        "ukz_rollback": {
          "count": 0,
          "sum": "0.00"
        },
        "withdraws": {
          "count": 2,
          "sum": "8.50"
        }
      }
    },
    "first_sale_number": 4,
    "last_sale_number": 13,
    "number": 1,
    "open_date": "2024-07-18T07:49:17+03:00",
    "sales_count": 10,
    "tax_number": 193141246,
    "total_income": {
      "BYN": "45.00"
    },
    "shift_mode": 0,
    "uid": "791261D74283114906A6E41E"
  }
}

Тип ReportCounter

Счетчики смены по одной валюте (значение currency_counters в Report).

{
  "sales": DocumentCounters,
  "money_backs": DocumentCounters,
  "rollbacks": DocumentCounters,
  "deposits": Counter,
  "withdraws": Counter,
  "client_withdraws": Counter,
  "cancels": Counter,
  "corrections": Counter,
  "marking_si": Counter,
  "marking_ukz": Counter,
  "si_refund": Counter,
  "si_rollback": Counter,
  "ukz_refund": Counter,
  "ukz_rollback": Counter,
  "additional": {
    "orders": {
      "total": Counter,
      "canceled": Counter,
      "closed": Counter,
      "corrected": Counter,
      "moved": Counter
    },
    "third_party": {
      "total": Counter,
      "rollback": Counter
    }
  },
  "cash_in": Sum,
  "sales_sum_with_change": i64?,
  "rate": { "sum": u64, "per": 1 | 10 | 100 }?
}

Counter:

{ "count": u32, "sum": Sum }

DocumentCounters:

{
  "count": u32,
  "sum": Sum,
  "cash": Sum,
  "card": Sum,
  "other": Sum,
  "other_desc": [ { "name": String, "sum": Sum } ],
  "discounts": Counter?,
  "markups": Counter?,
  "item_codes": {
    "prepayments": { "count": Quantity, "sum": Sum }?
  }?
}

Описание полей

• sales - счетчик продаж

• money_backs - счетчик возвратов

• rollbacks - счетчик аннулирований

• deposits - счетчик внесений

• withdraws - счетчик изъятий

• client_withdraws - счетчик выдачи

• cancels - счетчик отмен

• corrections - счетчик корректировок

• marking_si / marking_ukz - счетчики продаж СИ / УКЗ

• si_refund / ukz_refund - счетчики возврата СИ / УКЗ

• si_rollback / ukz_rollback - счетчики аннулирования СИ / УКЗ

• additional.orders - счетчики заказов (обслуживание за столиками)

• additional.third_party - счетчики операций в пользу 3-х лиц

• cash_in - наличные в кассе

• sales_sum_with_change - сумма продаж с учётом сдачи (в копейках). Только для магазинов беспошлинной торговли

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

• count - кол-во операций

• sum - сумма операций

• cash / card / other - суммы наличными / картой / иными способами

• other_desc - расшифровка иных способов оплаты по наименованиям

• discounts / markups - скидки / надбавки

• item_codes.prepayments - продажи товаров с кодом предоплаты

Используемые типы:

• Currency
• Sum
• Quantity

Тип TaxRate

enum имеющий следующие поддерживаемые значения:

• tax0
• tax10
• tax20
• tax25

Пример:

"tax0"

Тип TokenChequeHeader

{
  "cashier": String,
  "currency": Currency?,
  "section": ChequeSection?
}

Описание полей

• cashier - имя кассира. Не может превышать 20 символов длинной, не может быть пустым. Пробелы в начале и конце строки удаляются и таким образом гарантируется, что не будет передано пустое имя кассира
• currency - Валюта совершаемой операции, если не передано - byn
• section - секция чека. Применяется только для продажи и возврата:
  • code - u8 — код секции
  • name - String? — наименование секции

Используемые типы

• Currency

Тип Items

{
  "id": String?,
  "price": Sum,
  "quantity": Quantity,
  "discount": Sum?,
  `discount_info`: Discount_info?
  "markup": Sum?,
  `markup_info`: Markup_info?
  "code": ItemCode,
  "section": ItemSection,
  "name": String,
  "tax_rate": TaxRate?,
  "dfs_code": String?
}

Важно!: Поле name поддерживает только символы кодировки CP1251.

Описание полей

• id - клиентский идентификатор товарной позиции, на текущий момент не используется сервисом
• price - Цена товарной позиции за 1 единицу
• quantity - Кол-во товарной позиции
• discount - Скидка товарной позиции. В случае, если скидка не должна быть применена, должно быть передано значение null
• markup - Надбавка товарной позиции. В случае, если надбавка не должна быть применена, должно быть передано значение null
• code - Описание Кода товарной позиции
• section - Описание Секции товарной позиции
• name - Наименование товарной позиции. Не может быть пустым. Максимальная длина: 128 символов
• tax_rate - НДС. Важно помнить, что НДС0 и отсутствие НДС - разные вещи.
• discount_info / markup_info Наименования скидок/надбавок - позволяет указывать наименования и ключи группировки скидок/надбавок
• dfs_code - в магазине беспошлинной торговли для использования номера товара по системе учета товаров

Используемые типы

• Sum
• Quantity
• ItemCode
• ItemSection
• TaxRate

Тип ItemCode

"code": {
  "scan": [
    { "si": "SiTest" },
    { "ukz": "UKZTest" },
    { "gtin": "12134" }
  ]
}

Описание полей

code - Опциональное поле. Информация о коде и типе кода тов. позиции Представляет из себя обьект следующего формата: { "типКода": "значениеКода" } типКода может иметь следующие значения: code - без GTIN/EAN gtin - GTIN/EAN service - Услуга prepayment - Аванс

Важно! Вне зависимости от типа кода значениеКода может содержать исключительно цифры.

Важно! В случае, если типКода указан как gtin, максимальная длина значенияКода равна 14 символам. Для остальных случаев ограничение в 13 символов.

Важно! В маркировке встречается символ GS. Его требуется передавать как \u001D.

типКода так же может быть установлен в значение scan. В этом случае значениеКода передается как массив следующего формата: [ { "типСкана": "значениеСкана" } ] Где типСкана может иметь следующие значения: si - маркировка СИ ukz - маркировка УКЗ unknown - неизвестный тип маркировки gtin - GTIN товара

Тип ItemSection

"section": {
    "code": u8,
    "name": String?,
}

Описание полей

code - не обязательное поле, принимает значение от 0 до 255, 0 если номер секции отсутствует.

name - не обязательное поле, наименование секции для отображения на чеке

Тип Payment

{
  "payment_type": PaymentType,
  "name": String?,
  "value": Sum,
  "currency": String?,
  "group": { "key": String, "name": String }?
}

Описание полей

• payment_type - Тип платежа
• name - Наименование платежа. Может отсутствовать
• value - Сумма платежа
• currency - Валюта способа оплаты (применяется только в магазинах беспошлинной торговли)
• group - группа способа оплаты: key - ключ группировки, name - наименование группы

Важно: при продаже, возврате и оплате заказа (кроме смены МБТ) несколько способов оплаты cash объединяются в один перед фискализацией.

Используемые типы

• PaymentType
• Sum

Change

Тип Change

{
  "currency": String,
  "sum": Sum
}

Описание полей

• currency - Валюта сдачи
• sum - Сумма сдачи

Используемые типы

• Sum

Тип Dfs

{
  "customer": String,
  "doc_number": String,
  "train": String?,
  "flight": String?
}

Описание полей

• customer - Собственное имя и фамилия покупателя. Обязательное поле
• doc_number - Номер документа для выезда за границу. Обязательное поле
• train - Номер поезда. Может отсутствовать
• flight - Номер авиарейса. Может отсутствовать

Тип PaymentType

enum имеющий следующие поддерживаемые значения:

• cash - наличные
• card - банковская платежная карта (cashless - допустимый синоним)
• other - иные способы оплаты

Пример:

"card"

Тип Quantity

Данный тип представляет собой значение, с плавающей точкой, представленное в строковом виде.

В случае, если данное значение фигурирует во входных данных, оно обязано содержать 3 знака после запятой (иметь формат X.XXX), даже если последние равны 0 (например: 12345.000)

На данный тип наложен ряд ограничений:

1. Максимальное значение: 16777.215
2. Минимальное значение: 0

Данные ограничения продиктованы ограничениями протокола СККО.

Пример валидного значения Quantity:

"12345.607"

Тип DiscountInfo

Скидка

"discount_info": {
    "name": String,
    "group": String?
}

Надбавка

"markup_info": {
    "name": String,
    "group": String?
}

Описание полей

name - обязательное поле, наименование скидки/надбавки

group - не обязательное поле, ключ группировки скидок/надбавок

Тип State

{
  "last_uid": UID,
  "shift_state": ShiftState?,
  "user_data": String?,
  "trade_point_information": String?
}

Описание полей

• last_uid - УИ последнего документа
• shift_state - информация о смене. Отсутствует в случае, если смена закрыта
• user_data - Пользовательские данные в base64 формате
• trade_point_information - Информация о торговой точке

Используемые типы

• UID
• ShiftState

Тип Status

Возможные значения:

enum имеющий следующие поддерживаемые значения:

• unknown
• active
• blocked

Пример:

"active"

Тип Status

{
"type": "send",
"data": {
    "blockReasons": [BlockReason],
    "chwMaxValue": Int,
    "companyName": String,
    "isActive": Boolean,
    "rn": Int,
    "taxNumber": Int,
    "tradeAddr": String,
    "tradeName": String,
    "capabilities": [String]
    }
}

Описание полей

• blockReasons - причина блокировки возвращает объект {code: String, message: String}
• chwMaxValue - максимальное значение суммы выдачи в копейках
• companyName - название организации
• isActive - статус блокировки
• rn - рег. номер кассы
• taxNumber - УНП
• tradeAddr - адрес торговой точки
• tradeName - название торговой точки
• capabilities - список доступных возможностей, полученный с сервера

Все поля присутствуют всегда. tradeAddr/tradeName - пустые строки, если торговая точка не задана.

Тип ShiftState

{
  "next_cheque_number": u32,
  "shift_number": u16,
  "shift_open_date": DateTime,
  "cash_in": Map<Currency, Sum>,
  "shift_mode": i32
}

Описание полей

• next_cheque_number - номер следующего документа
• shift_number - номер текущей смены
• shift_open_date - Дата-время открытия смены
• cash_in - Информация о наличных в смене. Представляет собой объект, где ключом является наименование валюты и значением значение наличных в кассе
• shift_mode - числовой код режима, в котором открыта смена

Внесение/Изъятие/Выдача

Тип NewSumChequeRequest

{
  "sum_cheque_data": SumChequeData,
  "comments": Comments?,
  "user_data": String?
}

Описание полей

• sum_cheque_data - Информация по чеку
• comments - Комментарии к операции
• user_data - пользовательские данные, base64 строка не более 128 байт

Дополнительно на верхнем уровне (рядом с sum_cheque_data) принимаются поля доп. возможностей: unique_id, user_data, emails, trade_point_information, expand_marking_items.

Используемые типы

• SumChequeData
• Comments

Тип SumChequeData

{
  "header": TokenChequeHeader,
  "sum": Sum
}

Описание полей

• header - описание заголовка чека
• sum - сумма операции

Используемые типы

• TokenChequeHeader

Продажа

Тип SaleRequest

{
  "sale": NewSale,
  "comments": Comments?
}

Описание полей

• sale - описание продажи
• comments - комментарии к чеку

Дополнительно на верхнем уровне (рядом с sale) принимаются поля доп. возможностей: unique_id, user_data, emails, trade_point_information, expand_marking_items.

Используемые типы

• NewSale
• Comments

Тип NewSale

{
  "header": TokenChequeHeader?,
  "items": [ *Item ],
  "payments": [ *Payment ],
  "cheque_discount": Sum,
  "cheque_markup": Sum,
  "tp_tax_number": u32?,
  "change": [ *Change* ]?,
  "dfs": Dfs?
}

Описание полей

• header - описание заголовка чека
• items - массив товарных позиций
• payments - массив способов оплат
• cheque_discount - скидка по чеку
• cheque_markup - надбавка по чеку
• tp_tax_number - УНП 3-го лица

Дополнительные поля. Применяется только в магазинах беспошлинной торговли

• change - массив сумм и валют сдачи
• dfs - иная обязательная информация

Используемые типы

• TokenChequeHeader
• Item
• Payment
• Sum
• Dfs
• Change

Возврат

Тип NewMoneyBack

{
  "header": TokenChequeHeader,
  "items": [ Items ],
  "payments": [ *Payment* ]
}

Описание полей

• header - заголовок чека
• items - массив товарных позиций к возврату
• payments - Массив способов возврата. В случае возврата тип other игнорируется.

Используемые типы

• TokenChequeHeader
• Item
• Payment

Тип NewMoneyBackRequest

{
  "money_back": NewMoneyBack,
  "comments": Comments?
}

Описание полей

• money_back - информация для совершения операции возврата. Допустимо так же имя поля refund
• comments - комментарии к чеку

Дополнительно на верхнем уровне (рядом с money_back) принимаются поля доп. возможностей: unique_id, user_data, emails, trade_point_information, expand_marking_items.

Используемые типы

• NewMoneyBack
• Comments

Аннулирование

Тип NewRollback

{
  "header": TokenChequeHeader,
  "target_num": u32?
}

Описание полей

• header - заголовок чека. Для данного запроса поле currency игнорируется.
• target_num - номер чека, который необходимо аннулировать. Используется для валидации

Используемые типы

• TokenChequeHeader

Тип NewRollbackRequest

{
  "rollback": NewRollback,
  "comments": Comments?
}

Описание полей

• rollback - информация для совершения операции аннулирования

Используемые типы

• NewRollback
• Comments

Открытие смены

Тип OpenShiftRequest

{
  "mode": Mode?
}

Возможные значения mode. Необязательное поле:

• default или null - режим смены ретейл
• restaurant - режим смены ресторан (обслуживание за столиками)
• {"dfs": ModeDfs} - режим смены МБТ (магазин беспошлинной торговли), передаётся объектом: {"mode": {"dfs": {"kind": 0, "rates": {"USD": {"sum": 32512, "per": 1}}}}}
• gas - режим смены АЗС (для автозаправочных станций при продаже нефтепродуктов, сжиженных углеводородных газов)

Используемые типы

• ModeDfs

Тип ModeDfs

{
    "kind": Kind,
    "rates": Rates
}

Описание полей

• kind - тип смены МБТ. Обязательное поле
• rates - курсы валют в смене. Обязательное поле

Возможные значения Kind:

• 0 - указывается для магазинов типа 1 и магазинов типа 3
• 1- указывается для магазинов типа 2

Используемые типы

• Rates

Тип Rates

{
    "USD": {
      "sum": u64,
      "per": Per
    }
}

Описание полей

• currency - указывается валюта для применения заданных курсов
• sum - значение курса валюты в BYN, целое число с 4 знаками после запятой (например, 32512 = 3.2512)
• per - количество единиц иностранной валюты,

• Для работы в режиме магазина беспошлинной торговли (МБТ), при каждом открытии смены требуется ввести курсы валют:
  • Значение устанавливается для каждой валюты отдельно в эквиваленте добавленных валют с бэкофиса кассы с указанием суммы валюты при пересчете курса (за 1, 10, 100);
  • Курсы устанавливаются в BYN и передаются с 4 знаками после запятой;

Возможные значения Per:

• 1
• 10
• 100

Используемые типы

• Currency

Changelog

Изменения от 2026-11-02

Документация приведена в соответствие с tsrv 2.2.x.

Изменения tsrv по сборкам

2026.11.2

• Добавлена возможность установки размера QR-кода в коротком чеке: заголовок repr.custom.qr_size, допустимые значения - от 4 до 8
• В печатный расширенный отчёт добавлена информация по авансовым платежам и чистым итогам: "extra": ["cleanPayments"], см. Extra

2026.10.1

• Изменена работа usbprint: теперь используется единый хэндл для чтения/записи
• Добавлено дополнительное логирование ошибок принтера на Windows

2026.9.21

• В ik.service.printers/request добавлены заголовки printer.ignore_prefix и printer.ignore_postfix. При значении false к запросу будут добавлены данные из printer.prefix и printer.postfix соответственно. Значения по умолчанию - true
• В ответы get_tokens и get_token_by_serial добавлено поле cert_eol - время истечения срока ТСОК, см. TokenInformation
• Добавлено представление repr.printable_lines, см. FiscalResponse

2026.8.24

• Добавлен заголовок printer.postfix (аналогично printer.prefix, но после чека)
• Добавлена возможность печати копии документа выдачи через print_prev_receipt

2026.7.29

• ⚠️ Добавлена валидация полей unique_id, user_data, comments, emails, trade_point_information в фискальных методах (см. Доп. возможности). При передаче полей в некорректном формате возвращается ошибка req.format.json
• Добавлен заголовок repr.esc_pos.qr_generator.slot - слот для печати QR-кода на принтере. По умолчанию - 48 (0x30)
• Несколько платежей с типом cash объединяются в один (см. Payment). Пример:

  "payments": [
    { "payment_type": "cash", "value": "6.00" },
    { "payment_type": "cash", "value": "6.00" }
  ]
  

  Отображение на чеке:

  ------------------------------------------------
  Наличными:                                 12.00
  ------------------------------------------------
  

2026.4.7

• Обновление версии кассы до 2.2.0
• Доработки оптимизаций и улучшение быстродействия ПО
• Добавлена поддержка сборок под MacOS (собирается по запросу)

2026.2.19

• Исправлена попытка чтения из принтера, если передано "reply_size": 0

2026.2.16

• Существенная оптимизация логики работы с принтерами. Без изменений в рамках API
• Оптимизация логов в режиме INFO (по умолчанию) для более быстрой локализации проблем без включения более подробного уровня логирования
• Добавлен запрос ik.service.token/repr_prev_receipt - аналог print_prev_receipt, не требующий передачи заголовков выбора принтера (printer.usb.vendor/product, printer.spool.name, printer.dummy и т.д.)
• Исправлена проблема с поиском СКО после выхода из гибернации
• Добавлен заголовок printer.timeout - таймаут ожидания ответа от USB-принтера. По умолчанию - 15000 (15 с)
• Исправлены закэшированные ссылки для скачивания актуальных сборок
• Исправлена ошибка чтения данных из принтера

2026.1.27

• Исправлена работа при перезапуске в режиме службы Windows

2025.12.24

• Исправлена ошибка с максимальной длиной СИ

2025.12.19

• Добавлено поле id для Item. id учитывается при “схлопывании” маркированных товарных позиций в чеке
• Исправлен подсчёт кол-ва и суммы продаж товаров с типом кода “Предоплата”

2025.12.18

• Исправлена поддержка Linux (GLIBC 2.18)

2025.12.17

• Добавлены сферы применения МБТ и АЗС (см. Открытие смены)
• Добавлена возможность вывода кол-ва и суммы продаж товаров с типом кода “Аванс” в доп. отчёте (раздел после X/Z-отчёта)
• Добавлена сборка под Windows 7 (требует доп. настройки на рабочих местах, к использованию крайне не рекомендуется)

Изменения документации

Новое

• Новые методы:
  • repr_prev_receipt - представление ранее фискализированного чека без печати
  • get_certificate, render_non_fiscal_header
  • rates - курсы валют смены МБТ
  • get_order_information_by_id
• Заголовки: printer.postfix, printer.ignore_prefix / printer.ignore_postfix, printer.timeout, printer.file, printer.dummy.error, printer.debug, repr.text.b64, repr.printable_lines, repr.text.qr_generator, repr.ecs_pos.qr_generator.slot, repr.custom.* (короткий чек short, repr.custom.qr_size)
• Работа с принтером: принтер-файл, таймаут USB, usbprint.sys на Windows
• Extra: cleanPayments
• TokenInformation: cert_eol и описание всех полей
• FiscalResponse: repr.custom, repr.printable_lines
• Report / ReportCounter: актуальная структура счетчиков
• TokenChequeHeader: section; Payment: group, объединение нескольких оплат cash; PaymentType: card
• Копия документа выдачи доступна через print_prev_receipt
• Настройки: error_mappings, app.data_dir
• CLI: параметры upgrade-sko, analyze, команда change-pin
• Ошибки: коды ошибок tsrv, формат ответа для /tsrv/{address}/{action}
• Разделы Linux, особенности службы Windows

Исправлено / удалено

• Message: удалены ping/pong, reply_address, headers в ответе
• Коды ошибок TSRV_*, AVQFR_*, префикс USB_ заменены актуальными
• Заголовок rendering.sn → renderer.sn, refresh_tokens → tokens.refresh, поле text_b64 → text.b64
• Метод set_trade_point_info → set_trade_point_information
• Обновление прошивки вынесено в отдельный сервис ik.service.token.firmware
• Адрес по умолчанию - 127.0.0.1:1828; пути по умолчанию - относительно папки с исполняемым файлом
• Удалено поле id из SumChequeData, NewSale, NewMoneyBack, NewRollback (используйте unique_id)
• Удалено поле trade_point_name из TokenInformation; user_data и trade_point_information перенесены из ShiftState в State
• CloseShiftReq и PrintXReportReq объединены в ReportRequest
• OpenShiftRequest: поля kind и rates режима МБТ обязательны, rates.sum - целое
• Удалены страницы «Транспортный уровень» и «Менеджер СКО»

Изменения от 2025-12-15

• Удалены разделы, относящиеся к версии 1.8.x
• Добавлены типы относящиеся к режиму МБТ:
  • ModeDfs
  • Rates
• В NewSale добавлены поля для режима МБТ
• Для Windows добавлена команда detach-avtpcr, подробнее в CLI
• Добавлена информация про правила округления в режиме МБТ в Проверки
• Добавлены эндпоинты для обновления прошивки СКО в Firmware
• Добавлена возможность передавать наименования скидок/надбавок в Item
• Добавлена возможность вывода кол-ва и суммы авансовых платежей в X/Z-отчётах

Изменения от 2025-03-01

• Ошибки
  • Дополнен раздел с пояснениями для версии 2.x
• Общее описание принципов взаимодействия
  • Дополнено описание разделение ошибок для версии 2.x
• Список поддерживаемых заголовков
  • Удалены устаревшие заголовки
• Идентификатор операции
  • Операция больше не поддерживается в том же виде.
• Работа с СКО
  • Удалены устаревшие методы и разделы
  • Добавлено описание работы в случае версий 2.x+
• Служба (Windows)
  • Раздел помечен для 1.8.х
• Удалены разделы и методы приостановки и возобновления отправки док-в
• Сервисы
  • Для версии 2.х параметр token не является обязательным, если подключено 1 СКО
• Получение версии ПО
  • Добавлен пример для версии 2.x
  • Обновлена информация о типе данных Version
• Авторизация (authorize)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Смена пин-кода (change_pin)
  • Метод помечен для версии 1.8.х. В 2.х отсутствует
• logout
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Добавлен тип FiscalResponse
• Выдача (client_withdraw)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
• Внесение (deposit)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
• Изъятие (withdraw)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
• Возврат (create_money_back)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
• Аннулирование (create_rollback)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
  • Добавлена возможность передачи номера аннулируемого док-та для проверки соответствия с фронт-офисом
• Продажа (create_sale)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Убраны осуществляемые проверки
  • Добавлен пример возвращаемого ответа для v2.x
  • Добавлено указание возвращаемого типа для v2.x
  • Убраны примеры мат. вычислений
• Закрытие смены (close_shift)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Открытие смены (open_shift)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Добавлено описание входных значений для версии v2.x
• Получение X-отчёта (get_x_report)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Получение копии Z-отчёта
  • В 2.x версии метод отдает информацию только в закрытой смене и только по последней закрытой смене. Передача номера смены не требуется
• Открытие смены (create_sale)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Получение наличных в СКО (create_sale)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Печать счёта
  • Изменен входящий тип данных
• Отмена заказа
  • Изменен входящий тип данных
• Печать отложенного чека
  • Метод устарел и не поддерживается. Помечен “только для версии” 1.8.x
• Получение самого старого док-та в СКО (get_oldest_document)
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Получение номера первого и последнего док-та в смене
  • Не поддерживается в 2.x
• Получение ранее фискализированного чека
  • Не поддерживается в 2.x
• Получение кол-во неотправленных док-в
  • Добавлено описание того, как формируется выходное значение
• ShiftState
  • Добавлены поля trade_point_information и user_data
• TokenInformation2
  • Добавлен тип
• Получение информации об СКО
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Добавлено уточнение типа данных, возвращаемого на версии 2.x
• Получение СКО
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
  • Добавлено уточнение типа данных, возвращаемого на версии 2.x
• Получение номера след. док-та
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Печать ранее фиск. док-та
  • Убраны примеры неверных запросов и примеры ошибок (коды ошибок отличаются на 2.х и их кол-во увеличивается)
• Установка наименования торг. точки
  • Метод помечен как для версии 1.8.0. Недоступен, т.к. информация обязана запрашиваться от СККО
• Доп. возможности
  • Добавлено описание доп. возможностей для версии 2.x

Изменения от 2025-02-03

• Переменные окружения
  • Упразднены TSRV_REST_MODE и OPERATOR_CODE.
• Ошибки
  • Страница актуальна для версий 1.8.x
• Логирование
  • Добавлен раздел для версии 2.0.x
• Добавлен раздел CLI
• Настройки
  • Добавлен раздел для версии 2.0.x
• Менеджер СКО
  • Добавлена ссылка на Настройки для версии 2.x.y
• Работа с СКО
  • Раздел помечен как используемый для версий 1.8.x
• Заказы - Создан раздел

Изменения от 2024-07-01

Устревшие страницы документации:

• Удалена страница Сессии
• Удалена страница Инициализация сессии
• Удалена страница Хэш-значение id сессии
• Удалена страница Очистка сессии
• Удалена страница Регистрация продажи (внутр. БД товаров)
• Удалена страница Регистрация отмен
• Удалена страница ik.service.storage
• Удалена страница Сохранение товара
• Удалена страница Удаление товара
• Удалена страница Получение товара
• Удалена страница Получение известных идентификаторов товаров
• Удалена страница Комментарии
• Удалена страница HeaderComments
• Удалена страница BlockComments
• Удалена страница SaleComments
• Удалена страница ItemsBlockComments
• Удалена страница PaymentsComments
• Удалена страница DWComments
• Удалена страница RollbackComments
• Удалена страница MoneyBackComments
• Удалена страница BillComments
• Удалена страница ReportComments
• Удалена страница CountersComments
• Удалена страница ZReportCopyRequest
• Удалена страница NewMoneyBackEx
• Удалена страница ExNewMoneyBackRequest
• Удалена страница Возврат (внутр. БД товаров)
• Удалена страница ExSaleRequest
• Удалена страница NewSaleEx
• Удалена страница Хранилище
• Удалена страница StorageItem
• Удалена страница CancelRequest
• Удалена страница CloseShiftData
• Удалена страница CloseShiftRequest
• Удалена страница ExtendedCounters
• Удалена страница ItemEx

Устаревшие запросы:

Работа с сессиями:

• удалено action init_session
• удалено action clear_session
• удалено action get_active_session_hash
• удалено Header sid

Работа с принтерами и отрисовкой чеков

• удалено Header printer.code.policy
• удалено Header repr.text
• удалено Header repr.html
• удалено Header dreceipt.emails

Кассовые операции:

• удалено поле extra
• удалено action on_cancel
  • Тип CancelRequest
• удалено поле target_num для операции create_rollback
• удален Тип CloseShiftRequest
  • удален Тип CloseShiftData

Комментарии:

• удалено поле comments
  • удален Тип MoneyBackComments
  • удален Тип PaymentsComments
  • удален Тип ReportComments
  • удален Тип RollbackComments
  • удален Тип SaleComments
• удален Тип BlockComments
• удален Тип HeaderComments
• удален Тип ItemsBlockComments

Временно недоступны операции для Ресторанного режима:

• Тип OrderRequest
• Тип Order
• Тип PayOrderRequest
• Тип PrintBillRequest

Изменения:

• Для операции create_money_back поле Item заменено на Items и теперь принимает массив
• Изменения в структуре полей типа Items:
  • добавлено поле section:
    • добавлено поле code,
    • добавлено поле name.
  • изменено поле code:
    • удалено поле type,
    • удалено поле value,
    • добавлено поле scan.
  • добавлено поле markup
  • поле discount больше не принимает отрицательные значения
• Добавлено поле cheque_markup
• Добавлено поле tp_tax_number
• Для операции close_shift больше не требуется поле cashier
• Добавлено новый action в Header create_client_withdraw - операция Выдачи наличных
• Изменения в поле type_id и Типа ChequeType
  • новый тип client_withdraw_v2
  • изменено deposit -> deposit_v2
  • изменено money_back -> money_back_v2
  • изменено rollback -> rollback_v2
  • изменено sale -> sale_v2
  • изменено withdraw -> cashier_withdraw_v2
  • изменено z_report -> z_report_v2 для ChequeType
• изменено counters -> currency_counters и состав данных в сменных счетчиках
• поле cashier количество символов увеличено до 20

Ошибки

Добавлены ошибки:

• AVQFR_BAD_DOCUMENT_FORMAT = “bad document format”
• AVQFR_CH_WITHDRAW_MAX_SUM = ‘Сумма выдачи наличных держателю превышает максимально допустимую’
• AVQFR_CH_WITHDRAW_ONLY_BYN = ‘Выдача наличных держателю возможна только в белорусских рублях’
• AVQFR_MAX_DOC_COUNT_OVERFLOW = ‘Превышено максимальное количество документов в смене’
• AVQFR_TOO_MANY_ITEMS = ‘Превышено максимальное количество позиций в документе или размер документа слишком большой’
• CRT_MISSING_LEGAL_ADDR = “missing legal address in certificate”
• TIN_ONLY_SALE_ROLLBACK = “rollback can only be applied to sale”
• TIN_MARKING_QUANTITY_1 = “marking quantity should be 1”
• TIN_MULTIPLE_CASH_PAYMENTS = “multiple cash payments”
• TIN_TOO_MANY_MARKING_CODES = “too many marking codes”
• TIN_MULTIPLE_MARKING_CODES = “multiple marking codes”
• TIN_MARKING_CODE_LEN = “marking code len is exhausted”
• TIN_MARKING_CODE_WITHOUT_GTIN = “marking code without gtin”
• TIN_TOO_MANY_DISCOUNTS = “too many discounts”
• TIN_TOO_MANY_MARKUPS = “too many markups”
• TIN_EMPTY_ITEMS = “empty items”
• TIN_MISSING_LAST_SALE = “Отсутствует последний документ продажи”

Удалены ошибки:

• SM_SESSION_EXISTS = “session already exists. remove existing session or restart app”
• SM_INVALID_SESSION = “invalid session id”
• SM_SID_NOT_FOUND = “session id was not found”

Изменение от 2022-08-31

• Обновлен раздел Заголовки
• • Устарел заголовок printer.escpos.required
• • Добавлены заголовки repr.*
• Добавлен раздел Настройки
• Добавлен раздел Служба (windows)
• Обновлен тип SaleRequest
• • Устарело поле link

Пример ответа со всеми переданными заголовками repr.*:

{
  "type": "send",
  "data": {
    "header": {
      "cashier": "Test",
      "company_name": "ИП Моров А.М.",
      "currency": "BYN",
      "date_time": "2022-08-31T09:56:22.794436+03:00",
      "device_id": 131010705,
      "number": 10398,
      "serial_number": "AVQ11031010705",
      "shift_number": 878,
      "tax_number": 191832203,
      "trade_point_name": null,
      "type_id": "deposit",
      "uid": "1A5663901D4B4CE607CF1091"
    },
    "sum": "15.00",
    "repr": {
      "link": "https://receipts.test.imlab.by/?documentId=1A5663901D4B4CE607CF1091",
      "esc_pos": "G3QRICAgICAgICAgICAgICAgICCIjyCMruCuoiCALowuICAgICAgICAgICAgICAgICAgCiAgICAgICAgICAgICAgICAgk42POiAxOTE4MzIyMDMgICAgICAgICAgICAgICAgIAotLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0KG0UBICAgICAgICCNhSCfgoufhZKRnyCPi4CShYaNm4wghI6Kk4yFjZKOjCAgICAgICAgG0UACi0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQogICAgIISuquOspa3iIOClo6jh4uCg5qioIK6vpeCg5qioIKKtpeGlrajvICAgICAKICAgICAgICAgICAgICAgICAgICD8IDEwMzk4ICAgICAgICAgICAgICAgICAgICAgChtFAZCloy78IIqg4eHrOiAbRQAxMzEwMTA3MDUgG0UBh6CiLvwgkYqOOiAbRQBBVlExMTAzMTAxMDcwNQobRQGCoKvu4qA6IBtFAEJZTiAgICAbRQGErqot4iCnoKrg6+I6IBtFADMxLjA4LjIwMjIgMDk6NTY6MjIKG0UBiqDh4ajgOhtFAC4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi5UZXN0Ci0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQobRQGCraXhpa2uOhtFAC4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uLi4uMTUuMDAKLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tCiAgICAgICAgICCTiDogMUE1NjYzOTAxRDRCNENFNjA3Q0YxMDkxICAgICAgICAgIAobYTEdKGsDADFDAx0oawMAMUUxHShrGwAxUDAxQTU2NjM5MDFENEI0Q0U2MDdDRjEwOTEdKGsDADFRMAoKCgoKCh1WAQ==",
      "html": "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ИП&nbsp;Моров&nbsp;А.М.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;УНП:&nbsp;191832203&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br/>------------------------------------------------<br/><b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;НЕ&nbsp;ЯВЛЯЕТСЯ&nbsp;ПЛАТЕЖНЫМ&nbsp;ДОКУМЕНТОМ&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</b><br/>------------------------------------------------<br/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Документ&nbsp;регистрации&nbsp;операции&nbsp;внесения&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;№&nbsp;10398&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br/><b>Рег.№&nbsp;Кассы:&nbsp;</b>131010705&nbsp;<b>Зав.№&nbsp;СКО:&nbsp;</b>AVQ11031010705<br/><b>Валюта:&nbsp;</b>BYN&nbsp;&nbsp;&nbsp;&nbsp;<b>Док-т&nbsp;закрыт:&nbsp;</b>31.08.2022&nbsp;09:56:22<br/><b>Кассир:</b>.....................................Test<br/>------------------------------------------------<br/><b>Внесено:</b>...................................15.00<br/>------------------------------------------------<br/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;УИ:&nbsp;1A5663901D4B4CE607CF1091&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br/><br/>",
      "text": "                 ИП Моров А.М.                  \n                 УНП: 191832203                 \n------------------------------------------------\n        НЕ ЯВЛЯЕТСЯ ПЛАТЕЖНЫМ ДОКУМЕНТОМ        \n------------------------------------------------\n     Документ регистрации операции внесения     \n                    № 10398                     \nРег.№ Кассы: 131010705 Зав.№ СКО: AVQ11031010705\nВалюта: BYN    Док-т закрыт: 31.08.2022 09:56:22\nКассир:.....................................Test\n------------------------------------------------\nВнесено:...................................15.00\n------------------------------------------------\n          УИ: 1A5663901D4B4CE607CF1091          \n\n"
    }
  }
}

Изменения от 2022-04-18

• Добавлено описание заголовка dreceipt.emails в разделе Заголовки
• Добавлено описание заголовка printer.style в разделе Заголовки
• Добавлено описание заголовка printer.prefix в разделе Заголовки
• Добавлено поле cash_in в типе ShiftState
• Исправлено описание поведения в методе получения наличных СКО
• Добавлено описание поля link в SaleRequest
• Добавление описание заголовка printer.escpos.required в разделе Заголовки

Изменения от 2022-02-09

Документация:

• Исправлено описание входных данных при закрытии смены
• Добавлен тип CloseShiftData
• Исправлено описание в разделе Закрытие смены
• Добавлен пример с комментариями в разделе Закрытие смены

Изменения от 2022-02-02:

Документация:

• Добавлен ReportComments
• Добавлен CountersComments
• Добавлено поле comments в CloseShiftRequest
• Добавлен раздел “Очередь печати” в Работа с принтером
• Добавлена возможность печати копии Z-отчёта
• Добавлен тип ZReportCopyRequest
• Добавлена информация о конфигурации менеджера СКО
• Добавлены пути лог-конфигов в раздел Логирование