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

Введение

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

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

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

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

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

Message

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

{
  "type": MessageType,
  "address": String,
  "reply_address": String?,
  "data": Any?,
  "headers": Map<String, String>
}

MessageType передается как строка и может иметь следующие значения:

  • send - вызов метода
  • ping - запрос на проверку связи
  • pong - ответ на запрос проверки связи
  • error - сообщение сервера об ошибке

Поле type служит для объявления типа передаваемого сообщения. Список поддерживаемых сообщений со временем может расширяться.

Поле address имеет два значения в рамках протокола:

  • В случае клиентского сообщения, данное поле требуется для идентификации сервиса (dispatcher), который будет обслуживать данное сообщение
  • В случае серверного сообщения, данное поле заполняется значением из поля reply_address клиентского запроса, чтобы клиентская часть могла определить, на какое свое сообщение она получила ответ.

Поле reply_address является опциональным и служит для передачи "адреса", на котором будет ожидать ответа клиентская часть. Сервер, в свою очередь, данное поле оставляет всегда в значении null и после успешной/неуспешной обработки клиентского сообщения помещает значение данного поля в address серверного сообщения.

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

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

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

  • getTokenBySerial
  • get_token_by_serial
  • GET_TOKEN_BY_SERIAL
  • GetTokenBySerial

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

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

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

Примеры

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

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

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

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

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

{
  "type": "error",
  "address": null,
  "reply_address": null,
  "data": {
    "description": "dispatcher not found",
    "name": "TSRV_DISPATCHER_NOT_FOUND"
  },
  "headers": null
}

Комментарии

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

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

  • create_sale
  • create_withdraw
  • create_rollback
  • create_client_withdraw
  • create_money_back

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

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

  • before - комментарии, которые будут отображены перед заголовком чека
  • after - комментарии, которые будут отображены после UID'a
{
  "data": {
    "sale": { ... },
    "comments": {
      "before": [],
      "after": []
    }
  }
}

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

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

Параметры:

  • transient - true/false - отображать ли на электронном чеке
  • align - выравнивание комментария: CENTER, LEFT, RIGHT
  • size - размер QR кода (от 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": "Халва",
          "ref": "123414141124"
        }
      ],
      "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"
}

Данный раздел устарел на момент 2.x версии

ПК старается не хранить чеки на ФС, так же как не задерживать их внутри памяти СКО.

Требуется хранить информацию на уровень интеграции, если в этом есть необходимость. Вся остальная информация может быть получена из ЛК СХ.

Идентификатор операции

В запросах:

Дополнительно может быть передано поле id - идентификатор операции. Оно используется для поиска копии чека.

Пример:

  1. Создаём запрос на продажу, с полем id=cc20dd90-85d4-4c2a-b55f-a637a82a5bd3
{
  "address": "ik.service.token.sales.retail",
  "headers": {
    "action": "create_sale",
    "token": "AVQ11169990665",
    "printer.dummy": "",
    "repr.esc_pos": true
  },
  "data": {
    "sale": {
      "header": {
        "cashier": "Test",
        "currency": "BYN"
      },
      "items": [
        {
          "code": {
            "gtin": "978020137962"
          },
          "price": "7.00",
          "quantity": "2.000",
          "name": "Это мой первый товар и под ним есть values",
          "discount": "3.00",
          "markup": "1.00",
          "tax_rate": "tax20"
        },
        {
          "code": {
            "gtin": "978020137962"
          },
          "price": "7.00",
          "quantity": "2.000",
          "name": "А вот второй.. Но тут тоже есть values",
          "discount": "3.00",
          "markup": "1.00",
          "tax_rate": "tax20"
        }
      ],
      "payments": [
        {
          "payment_type": "cashless",
          "value": "24.00",
          "name": "Халва",
          "ref": "123414141124"
        }
      ],
      "cheque_discount": "0.00",
      "cheque_markup": "0.00",
      "tp_tax_number": 123456789,
      "id": "cc20dd90-85d4-4c2a-b55f-a637a82a5bd3"
    }
  },
  "type": "send"
}
  1. Получаем копию чека по id=cc20dd90-85d4-4c2a-b55f-a637a82a5bd3
{
  "address": "ik.service.token",
  "headers": {
    "action": "get_receipt",
    "token": "AVQ11169990665"
  },
  "data": {
    "number": 0,
    "id": "cc20dd90-85d4-4c2a-b55f-a637a82a5bd3"
  },
  "type": "send"
}
  • Важно! Поле id должно быть уникальным для каждой операции.
  • Важно! Поле number должно присутствовать, но оно будет игнорироваться.
  • Важно! В случает если id не уникально, то будет возвращена ошибка TIN_ID_ALREADY_EXISTS

Ошибки (v2.x)

В случае возникновения ошибки, сервер отправит сообщения с типом error и полем data следующего вида:

{
    "description": String,
    "name": String
}

В случае возникновения ошибок на методах, отвечающих за фискализацию, ошибки, которые возникли ПОСЛЕ фискализации, помещаются в отдельное поле 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.

Ошибки (v1.8.x)

В случае возникновения ошибки, сервер отправит сообщение типом error и полем data следующего вида:

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

Для идентификации ошибки на клиентской стороне требуется ориентироваться на поле name, т.к. оно является гарантированно уникальным в рамках протокола.

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

Так же, текстовое описание ошибок description может меняться/дополняться в рамках работы сервиса и, как следствие, полагаться на него как на уникальное значение запрещается.

Перечень ошибок, возможных в рамках протокола ошибок:

[errors]
AVQFR_INVALID_COMMAND = 'подана команда с неизвестным кодом или нарушен порядок подачи команд'
AVQFR_UNSUPPORTED_VERSION = 'версия протокола взаимодействия с устройством не поддерживается'
AVQFR_ACCESS_DENIED = 'неверно указана роль при авторизации (отличная от PIN, PUK или REG)'
AVQFR_BAD_SERIAL_NUMBER = 'неверно задан серийный номер устиойства'
AVQFR_BAD_DEVICE_MODE = 'команда не может быть выполнена в текущем режиме устройства'
AVQFR_INTERNAL_ERROR = 'внутренняя ошибка (возможная причина - аппаратный сбой)'
AVQFR_TIMEOUT = 'превышено время ожидания ответа при синхронизации времени'
AVQFR_BAD_FW_UPGRADE_KEY = 'отсутствует ключ обновления прошивки или его целостность нарушена'
AVQFR_NOT_MOUNTED = 'файловая система на смонтирована (внутренняя ошибка, устройство неисправно)'
AVQFR_NOT_FORMATTED = 'носитель на отформатирован (внутренняя ошибка, устройство неисправно)'
AVQFR_INSUFFICIENT_SPACE = 'недостаточно места для записи данных'
AVQFR_FILE_IS_TOO_BIG = 'превышен размер файла (внутренняя ошибка, устройство неисправно)'
AVQFR_FILE_NOT_EXIST = 'файл не найден, необходимые данные отсутствуют'
AVQFR_FILE_ALREADY_EXISTS = 'файл уже имеется (внутренняя ошибка, устройство неисправно)'
AVQFR_INVALID_OFFSET = 'неверное смещение (внутренняя ошибка, устройство неисправно)'
AVQFR_PROGRAM_ERROR = 'ошибка записи во флеш-память (внутренняя ошибка, устройство неисправно)'
AVQFR_BAD_ADDRESS = 'неверно задан адрес блока памяти (внутренняя ошибка, устройство неисправно)'
AVQFR_ERASE_ERROR = 'ошибка стирания флеш-памяти (внутренняя ошибка, устройство неисправно)'
AVQFR_NO_CIPHER_CALLBACKS = 'функции шифрования файловой системы недоступны (внутренняя ошибка, устройство неисправно)'
AVQFR_MAC_NOT_FOUND = 'у файла отсутствует имитовставка (внутренняя ошибка, устройство неисправно)'
AVQFR_NOT_ACTUAL_KEY = 'срок действия ключа не наступил или истек'
AVQFR_BAD_SIGN = 'подпись не верна'
AVQFR_INCORRECT_PARAM_SIZE = 'неверный размер параметра (один из параметров команды имеет неверную длину)'
AVQFR_BAD_SYNC_REQUEST_ID = 'неверный идентификатор запроса синхронизации времени'
AVQFR_BAD_FILE_INDEX = 'недопустимое имя файла (внутренняя ошибка, устройство неисправно)'
AVQFR_NO_DATA = 'запрашиваемые данные отсутствуют (попытка получить внутренний или отсутствующий документ)'
AVQFR_INTEGRITY_ERROR = 'нарушение целостности данных, хранящихся в устройстве (устройство неисправно)'
AVQFR_PRNG_NOT_INITIALIZED = 'генератор СЧП не инициализирован, инициализация устройства не завершена'
AVQFR_BAD_SIGN_CTR = 'неверное значение счетчика подписей'
AVQFR_BAD_STATUS_CODE = 'неверное значение кода завершения обработки запроса сервером'
AVQFR_INVALID_MODE = 'неверно задан режим алгоритма (внутренняя ошибка, устройство неисправно)'
AVQFR_INCORRECT_PARAM = 'один из переданных параметров имеет недопустимое значение'
AVQFR_SELF_TEST_FAILURE = 'ошибка самотестирования (устройство неисправно)'
AVQFR_SHIFT_IDLE_TIMEOUT = 'превышено время бездействия, требуется синхронизация времени'
AVQFR_BAD_KEY_AUTH_DATA = 'неверные данные для авторизации сессии (неверное значение PIN, PUK или REG)'
AVQFR_INVALID_ATTR_ID = 'неверный идентификатор атрибута устройства (атрибут, не поддерживается устройством)'
AVQFR_BAD_KEY_TOKEN = 'токен ключа сформирован некорректно'
AVQFR_FILE_BACKUP_ERROR = 'ошибка дублирования файла (внутренняя ошибка, устройство неисправно)'
AVQFR_BAD_KEY_ID = 'идентификатор ключа отсутствует или имеет неверный размер'
AVQFR_BAD_KEY = 'ключ отсутствует, имеет неверный размер или неверный формат набора ключей'
AVQFR_ASN1_PARSE_ERROR = 'невозможно разобрать ASN1-структуру (нарушена структура сертификата или ответа сервера)'
AVQFR_INCORRECT_DATA_SIZE = 'неверный общий размер данных команды (передана команда неподдерживаемой длины)'
AVQFR_SESSIONS_LIMIT_EXCEEDED = 'слишком много одновременно открытых сессий'
AVQFR_INVALID_SESSION_ID = 'неверный идентификатор сессии'
AVQFR_SHIFT_IS_PENDING = 'необходимо закрыть смену'
AVQFR_RECEIPT_IS_PENDING = 'в устройстве присутствуют кассовые документы, которые необходимо передать на сервер'
AVQFR_RECEIPT_SUM_OVERFLOW = 'переполнение счетчиков, необходимо закрыть смену'
AVQFR_RECEIPT_NEGATIVE_VALUE = 'задано отрицательное значение суммы'
AVQFR_NEGATIVE_SHIFT_BALANCE = 'получен отрицательный сменный баланс'
AVQFR_SESSION_ALREADY_AUTHORIZED = 'сессия уже авторизована (попытка повторной авторизации уже авторизованной сессии)'
AVQFR_SESSION_NOT_AUTHORIZED = 'сессия не авторизована (команда требует обязательной авторизации)'
AVQFR_SESSION_EXISTS = 'имеется открытая сессия (выполнение команды возможно только в монопольном режиме)'
AVQFR_SHIFT_IS_OPENED = 'смена открыта (команда возможна только при закрытой смене)'
AVQFR_SHIFT_IS_CLOSED = 'смена закрыта (команда возможна только при открытой смене)'
AVQFR_BAD_DATE_TIME = 'неверный формат или значение даты или времени (операция выполняется "задним" числом)'
AVQFR_BAD_CASH_REG_NUMBER = 'неверный номер кассового аппарата (номер КСА в СККО)'
AVQFR_BAD_CURRENCY_NAME = 'неверное наименование кода валюты'
AVQFR_BAD_RECEIPT_TYPE = 'неверный тип кассового документа'
AVQFR_BAD_RECEIPT_NUMBER = 'номер кассового документа отличается от значения внутренего счетчика кассовых документов'
AVQFR_BAD_RECEIPT_COST = 'рассогласование по полю "Итого общая стоимость"'
AVQFR_BAD_RECEIPT_DISCOUNT = 'рассогласование по полю "Сумма скидки (надбавки)"'
AVQFR_BAD_RECEIPT_TOTAL = 'рассогласование по полю "Итого к оплате"'
AVQFR_BAD_RECEIPT_CENTS = 'неправильное значение дробной части денежного поля'
AVQFR_BAD_TAXPAYER_NUMBER = 'задан неверный УНП'
AVQFR_BAD_CORRECTION_VALUE = 'задана ненулевая сумма коррекции при отсутствии коррекций'
AVQFR_TOTAL_TRADE_OVERFLOW = 'переполнение счетчика суммарного торгового оборота'
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 = 'Превышено максимальное количество позиций в документе или размер документа слишком большой'
AVQFR_UNKNOWN = 'неизвестная ошибка'

TR_EMPTY_INPUT = 'неверные входные данные (данные отсутствуют)'
TR_INVALID_TYPE = 'неверный тип данных'
TR_INSUFFICIENT_BYTES = 'недостаточно данных для считывания информации'

USB_IO = "Input/Output Error"
USB_INVALID_PARAM = "Invalid parameter"
USB_ACCESS = "Access denied (insufficient permissions)"
USB_NO_DEVICE = "No such device (it may have been disconnected)"
USB_NOT_FOUND = "Entity not found"
USB_BUSY = "Resource busy"
USB_TIMEOUT = "Operation timed out"
USB_OVERFLOW = "Overflow"
USB_PIPE = "Pipe error"
USB_INTERRUPTED = "System call interrupted (perhaps due to signal)"
USB_NO_MEM = "Insufficient memory"
USB_NOT_SUPPORTED = "Operation not supported or unimplemented on this platform"
USB_BAD_DESCRIPTOR = "Malformed descriptor"
USB_OTHER = "Other error"

CRT_MISSING_DEVICE_ID = "missing device id"
CRT_MISSING_OWNER_TAX_NUMBER = "missing owner tax number"
CRT_MISSING_OPERATOR_CODE = "missing operator code"
CRT_MISSING_SERIAL_NUMBER = "missing serial number"
CRT_MISSING_OWNER_NAME = "missing owner name in certificate"
CRT_MISSING_LEGAL_ADDR = "missing legal address in certificate"
CRT_MISSING_CERT_SERIAL = "missing cert serial"
CRT_INVALID = "invalid certificate"

AVTPCR_ATTR_NOT_FOUND = 'missing required attribute'

TIN_CODE_LEN = "invalid code length"
TIN_EMPTY_NAME = "empty name"
TIN_NAME_LEN = "invalid name length"
TIN_INVALID_GTIN = "invalid gtin/ean"
TIN_ZERO_SUM = "invalid sum: can't be 0"
TIN_NEGATIVE_SUM = "invalid sum: can't be negative"
TIN_SUM_OVERFLOW = "sum overflow"
TIN_QUANTITY_OVERFLOW = "quantity overflow"
TIN_ZERO_QUANTITY = "invalid quantity: 0"
TIN_EMPTY_CASHIER = "empty cashier name"
TIN_NO_ITEMS = "invalid items array: no items"
TIN_MAX_ITEMS = "too many items"
TIN_NOT_ENOUGH_MONEY = "not enough payed"
TIN_CASHLESS_OVERFLOW = "too much cashless payment"
TIN_CASH_OVERFLOW = "too much cash"
TIN_NEGATIVE_CHANGE = "invalid change: can't be negative"
TIN_CASHIER_LEN = "invalid cashier length"
TIN_NOT_ENOUGH_CASH_IN = "not enough money in cash box"
TIN_ONLY_SALE_ROLLBACK = "rollback can only be applied to sale"
TIN_WRONG_ROLLBACK_DOC_NUM = "trying to rollback wrong doc num"
TIN_ID_ALREADY_EXISTS = "cheque with given id already exists"
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 = "Отсутствует последний документ продажи"

TSRV_APP_WAS_NOT_CONFIGURED = "application was not configured properly"
TSRV_EMPTY_ADDRESS = "no address provided"
TSRV_DISPATCHER_NOT_FOUND = "dispatcher not found"
TSRV_DESERIALIZE_ERROR = "failed to deserialize value"
TSRV_EMPTY_MSG_DATA = "data field is required but was not provided"
TSRV_ACTION_NOT_FOUND = "'action' was not found"
TSRV_INVALID_HEADER = "invalid header value"
TSRV_TOKEN_NOT_FOUND = "token was not found"
TSRV_INVALID_SUM_DEC_PART = "invalid sum decimal part. should always have 2 digits after dot"
TSRV_INVALID_QUANTITY_DEC_PART = "invalid quantity decimal part. should always have 3 digits after dot"
TSRV_NEGATIVE_CHEQUE_DISCOUNT = "cheque discount can't be negative"
TSRV_TOKEN_NOT_ACTIVE = "СКО не активно"
TSRV_ITEM_NOT_FOUND = "item was not found in storage"

PR_IO_ERROR = "printer I/O error"
PR_NOT_FOUND = "printer was not found"
PR_USB_ERROR = "usb printer error"

TORD_FAILED_TO_REMOVE = "failed to remove prev order"
TORD_FAILED_TO_DESER = "failed to deserialize prev order (file may be corrupted)"
TORD_READ_FAILED = "failed to read order"
TORD_WRITE_FAILED = "failed to write order"
TORD_NOT_FOUND = "order was not found"

Что делать если была возвращена ошибка...

  • AVQFR_NOT_ACTUAL_KEY - требуется проверить срок действия СКО и обратиться в тех. поддержку

  • AVQFR_BAD_KEY_AUTH_DATA - PIN/PUK код имеются неверные значения - проверить их правильность в соответствии с паспортом СКО

  • AVQFR_SHIFT_IDLE_TIMEOUT - требуется проверить подключение к интернету и попытаться открыть смену. При открытии смены осуществляется попытка синхронизации времени

  • AVQFR_INSUFFICIENT_SPACE - слишком много неотправленных документов - подключиться к интернету, проверить, что пройдена авторизация по PIN коду. Максимальное кол-во документов - около 4000

  • AVQFR_SESSIONS_LIMIT_EXCEEDED - Программная касса завершала свою работу некорректно какое-то кол-во раз. Требуется обратиться в тех. поддержку предоставив лог-файл и для продолжения работы - достать и вернуть СКО в устройство с запущенной программной кассой

  • AVQFR_SHIFT_IS_PENDING - требуется закрытие смены.

  • AVQFR_RECEIPT_IS_PENDING - требуется проверка наличия интернета на устройстве и убедиться, что пройдена авторизация по PIN коду, а так же дождаться, пока документы будут отправлены на сервер. Кол-во неотправленных документов можно получить с помощью метода get_stored_documents

  • AVQFR_RECEIPT_SUM_OVERFLOW - прибыль вашей компании за смену достигла невероятных объемов. Требуется закрыть смену и сообщить в тех. поддержку о данной ошибке

  • AVQFR_NEGATIVE_SHIFT_BALANCE - попытка уменьшения кол-ва наличных в кассе в отрицательную сторону - например операцией возврата или изьятия. это является ошибкой клиентского ПО и должно быть устранено на этапе интеграции. Так же данная ошибка может возникать при попытке закрытия смены, что говорит о том, что имеются наличные в кассе, которые подлежат изъятию перед закрытием смены

  • AVQFR_SESSION_ALREADY_AUTHORIZED - уже пройдена авторизация в СКО

  • AVQFR_SESSION_NOT_AUTHORIZED - требуется прохождение авторизации в СКО

  • AVQFR_SHIFT_IS_OPENED - требуется закрыть смену

  • AVQFR_SHIFT_IS_CLOSED - требуется открыть смену

  • AVQFR_BAD_DATE_TIME - требуется проверить время на устройстве

  • TIN_CODE_LEN - требуется проверить длину кода. Длина кода не должна превышать 13 знаков.

  • TIN_EMPTY_NAME - имя является обязательным полем, требуется проверить, что оно заполнено

  • TIN_NAME_LEN - неверная длина имени тов. позиции. Не должна превышать 128 символов

  • TIN_INVALID_GTIN - не пройдена валидация кода GTIN (проверочный знак неверный)

  • TIN_ZERO_SUM - значение цены/суммы не может быть равно 0 в одном из полей

  • TIN_NEGATIVE_SUM - значение цены/суммы не может быть отрицательным

  • TIN_SUM_OVERFLOW - слишком большое/маленькое значение цены/суммы. Об ограничениях написано в описании типа Sum

  • TIN_QUANTITY_OVERFLOW - слишком большое значение кол-во. Об ограничениях написано в описании типа Quantity

  • TIN_ZERO_QUANTITY - кол-во не может быть равно 0.

  • TIN_EMPTY_CASHIER - имя кассира не может быть пустым. Это обязательное поле

  • TIN_NO_ITEMS - попытка совершения продажи без товарных позиций

  • TIN_MAX_ITEMS - слишком много товарных позиций в чеке

  • TIN_NOT_ENOUGH_MONEY - недостаточная сумма при попытке оплаты чека

  • TIN_CASHLESS_OVERFLOW - слишком много безналичных средств. Ошибка возникает если значение способов безналичной оплаты и других способов оплаты превышает сумму. С данных способов оплаты невозможно выдать сдачу

  • TIN_CASH_OVERFLOW - слишком много наличных средств. Возникает если сумма безналичных и других способов оплаты полностью покрываем сумму по чеку, а наличные не равны 0

  • TIN_NEGATIVE_CHANGE - Отрицательная сдача.

  • TIN_CASHIER_LEN - неверная длина кассира. Превышает 20 символов

  • TIN_NOT_ENOUGH_CASH_IN - недостаточно наличных в кассе для совершения операции. Например, для выдачи сдачи

  • TSRV_APP_WAS_NOT_CONFIGURED - ошибка инициализации ПО. Требуется обратиться в тех. поддержку

  • TSRV_EMPTY_ADDRESS - не указано значение поля address в запросе, либо пустое значение

  • TSRV_DISPATCHER_NOT_FOUND - неверное значение address в запросе

  • TSRV_DESERIALIZE_ERROR - ошибка обработки входных данных. Требуется проверка правильности формата и указание обязательных полей

  • TSRV_EMPTY_MSG_DATA - требуемое тело запроса (поле data) отсутствует

  • TSRV_ACTION_NOT_FOUND - неверное значение заголовка action , либо address указан неверно

  • TSRV_INVALID_HEADER - неверное значение одного из заголовков

  • TSRV_TOKEN_NOT_FOUND - СКО не найдено

  • TSRV_INVALID_SUM_DEC_PART - неверное значение суммы (передано не в формате X.XX)

  • TSRV_INVALID_QUANTITY_DEC_PART - неверное значение кол-ва (передано не в формате X.XXX)

  • TSRV_NEGATIVE_CHEQUE_DISCOUNT - отрицательная скидка по чеку (надбавка на чек недоступна)

  • TSRV_TOKEN_NOT_ACTIVE - СКО заблокировано

  • TSRV_ITEM_NOT_FOUND - товар отсутствует в БД товаров

  • PR_IO_ERROR - ошибка чтения/записи принтера

  • PR_NOT_FOUND - принтер с указанными данными не найден

  • PR_USB_ERROR - ошибки при работе с принтером по USB

  • TORD_FAILED_TO_REMOVE - ошибка удаления предыдущего заказа

  • TORD_FAILED_TO_DESER - файл заказа поврежден либо не может быть обработан. Требуется пересоздать заказ предварительно удалив

  • TORD_READ_FAILED - ошибка чтения заказа из ФС. Требуется обратиться в тех. поддержку

  • TORD_WRITE_FAILED - ошибка записи заказа в ФС. Требуется обратиться в тех. поддержку

  • TORD_NOT_FOUND - заказ с данным идентификатором не найден. Требуется создание заказа

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

СКО

  • token - серийный номер СКО
  • tokens.refresh - обновление списка СКО * token.trade_point.information - установить в запросе доп. информацию о торговой точке

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

  • printer.[usb|dummy] - заголовки и подзаголовки для работы с принтерами
  • printer.spl - spl - symbols per line. Указание кол-ва символов в ширину на бумаге, на которой будет происходить печать. По умолчанию: 48
  • printer.cp866 - указание номера таблицы символов в принтере соответствующий кодировке CP866. По умолчанию - 17
  • printer.cp1251 - указание номера таблицы символов в принтере соответствующий кодировке CP1251. По умолчанию - 18
  • printer.feed - указание кол-во строк прокрутки бумаги после печати. По умолчанию: 5
  • printer.cut - принудительное отрезание бумаги после завершения печати. По умолчанию: true
  • printer.prefix - данные для печати перед печатью основного чека. Может быть использовано для печати лого или изменении шрифта для последующей печати * printer.style - вид печати чека. по умолчанию - default, печатает полный чек. При указании значения qr будет напечатан чек с QR кодом, в котором содержится ссылка на эл. чек * DEPRECATED printer.escpos.required - требуется ли передача escpos представления чека в ответе. В случае, если значение true, escpos команды в base64 формате будут помещены в поле extra ответов.

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

  • repr.esc_pos - отдавать в объекте фискального документа дополнительный объект repr с полем esc_pos, в котором находится esc_pos (base64) представление чека
  • repr.text - отдавать в объекте фискального документа дополнительный объект repr с полем text, в котором находится текстовое представление чека
  • repr.link - отдавать в объекте фискального документа дополнительный объект repr с полем link, в котором находится ссылка на эл. чек

Важно!

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

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

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

Общее

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

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

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

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

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

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

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

  • USB
  • Dummy

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

USB-принтер

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

  • printer.usb.vendor - строковое представление vendorId устройства
  • printer.usb.product - строковое представление productId устройства

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

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

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

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

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

Dummy-принтер

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

Delayed принтер

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

Для использования этого типа принтера требуется передать заголовок printer.delayed с тем же идентификатором, что будет передан в printer.delayed.id

При использовании данного способа требуется передача дополнительного заголовка: printer.delayed.id c идентификатором для последующей печати. В качестве идентификатора можно использовать номер следующего документа в смене.

Печать отложенного чека может быть совершена с помощью метода print_delayed

Работа с СКО (v2.0.1+)

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

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

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

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

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

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

Работа с СКО (v1.8.x)

Для корректного запуска приложения и работы с СКО, требуется объявление переменной окружения OPERATOR_CODE с указанием кода оператора. На основании кода оператора будут доступны устройства с соответствующим кодом оператора.

Доступные коды оператора:

  • 5 - dev окружение iKassa
  • 910000001 - stage окружение iKassa, используемое Республиканским Унитарным Предприятием "Информационно-Издательский Центр Министерства по Налогам и Сборам" (РУП ИИЦ МНС)
  • 1 - prod окружение iKassa, используемое на реальных торговых точках

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

Запросить текущий статус СКО можно с помощью метода get_status

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

Важно: на старте приложения осуществляется поиск доступного СКО.

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

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

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

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

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

1.8.x

  • TSRV_ADDR - адрес, который будет слушаться HTTP сервером. По умолчанию - 0.0.0.0:1828
  • TSRV_REST_MODE - переменная окружения для переключения режима работы Программной Кассы в режим обслуживания за столиками. Должно иметь значение true или false. Значение по умолчанию false
  • OPERATOR_CODE - код оператора. Описано в разделе Работа с СКО

2.0.x

  • TSRV_ADDR - адрес, который будет слушаться HTTP сервером. По умолчанию - 127.0.0.0:1828

Логирование (v2.0.x)

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

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

Настройки:

  1. Путь по умолчанию: ./configs/log.yaml
  2. Путь к файлу может быть настроен с помощью аргументов при запуске ПО
    • Например: tsrv --logs-config C:/tsrv/log-config.yaml

Логирование (v1.8.x)

По умолчанию установлен INFO уровень логирования всех модулей в stdout (консоль).

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

refresh_rate: 15 seconds 
appenders:              
  stdout:
    kind: console

  receipts:               # (1) Дополнительное правило логирования 
    kind: console         # В консоль (stdout)
    encoder:    
      pattern: "{m}{n}"   # Шаблон. {m} - сообщение, {n} - перенос
root:
  level: info             # Уровень логирования для всех модулей
  appenders:
    - stdout

loggers:
  tsrv_renderer::esc_pos: # Данный модуль отвечает за преобразование в EscPos команды
    level: trace          # Уровень логирования
    appenders:
      - receipts          # (1)
    additive: false      

  actix_server::worker:
    level: warn
    appenders:
      - stdout

Путь конфигурационного файла зависит от ОС:

ОСПутьПример
Linux$XDG_CONFIG_HOME или $HOME/.config/home/alice/.config/.tsrv/log.yaml
Windows%AppData%C:\Users\Alice\AppData\Roaming\.tsrv\log.yaml

Конфигурация Менеджера СКО (v2.0.0+)

См Настройки

Конфигурация Менеджера СКО (v1.8.x)

Менеджер СКО отслеживает новые подключения СКО и может совершать над ними какие-либо операции, например - автоматическая авторизация

Пример конфигурационного файла:

tokens:
  AVQ11071080687:
    auto_login: true
    pin_code: 20740

В разделе tokens описываются СКО и конфигурации к ним.

  • auto_login - требуется ли автоматический вход (по умолчанию - false)
  • pin_code - PIN-код СКО. Если значение отсутствует - вход не будет выполнен.
    • В случае неверного pin-кода в лог будет выведена ошибка и потребуется совершать вход согласно протокола

Путь конфигурационного файла зависит от ОС:

ОСПутьПример
Linux$XDG_CONFIG_HOME или $HOME/.config/home/alice/.config/.tsrv/token_manager_conf.yaml
Windows%AppData%C:\Users\Alice\AppData\Roaming\.tsrv\token_manager_conf.yaml

Настройки (2.0.x)

Настройки:

  • trade_point
    • information - доп. информация о торговой точке для печати
  • tokens - настройки работы с СКО
    • {СЕРИЙНЫЙ_НОМЕР_СКО} - указывается серийный номер СКО
      • auto_login - true | false - флаг, для автоматической авторизации в СКО. Попытка авторизации совершается 1 раз, как только найдено СКО
      • pin_code - значение пин кода для авторизации. Требуется при указании auto_login
  • headers
    • defaults - перечисление заголовком по умолчанию
  • server
    • addr - указание адреса и порта, который будет слушать ПО
  • renderer
    • replacements
      • {кодировка} - указывается кодировка, либо cp866, либо cp1251
        • Список символов для замены
          • char - одиночный символ для замены
          • with - символ, на который заменять
    • comments - комментарии, которые будут печататься на всех док-тах продажи
      • before - До чека
        • Список объектов
      • after - После чека
        • Список объектов

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

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:8080

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

Настройки (1.8.x)

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

headers:
  defaults:
    repr.esc_pos: true
    repr.text: true
    repr.link: true
    token: AVQ11031010705
    printer.dummy: ''

Путь конфигурационного файла зависит от ОС:

ОСПутьПример
Linux$XDG_CONFIG_HOME или $HOME/.config/home/alice/.config/.tsrv/settings.yaml
Windows%AppData%C:\Users\Alice\AppData\Roaming\.tsrv\settings.yaml

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

  • Установить tsrv как сервис
    • Рядом с tsrv.exe создать файл по имени install.bat со следующим содержимым:
    cd %~dp0
.\tsrv.exe --install-service --test
pause
    • Запустить install.bat от администратора
  • Альтернативный способ:
    • Запустить cmd.exe от Администратора
    • Выполнить c:\путь\к\tsrv.exe --install-service --test
  • Проверить, что сервис успешно запустился:
    • sc query tsrv-native
    • В случае, если сервис не в статусе RUNNING необходимо посмотреть логи сервиса
  • ⚠️ При переходе из тестовой зоны в боевую необходимо вызывать инсталлер с ключом --prod вместо --test. Это заведёт правильную переменную окружения для работы кассы.

Логи сервиса

  • Логи складываются в %AppData%\.tsrv\.logs
  • Так как сервис запускается под пользователем LocalSystem, логи можно найти по пути C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\.tsrv\.logs
  • [необязательно] Чтобы логи и файлы конфигурации складывались в не-системного пользователя, необходимо сменить пользователя в service.msc для сервиса TSRVNative, это поддерживается

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

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

Обработка ошибок (v2.0.1+)

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

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

Обработка ошибок (v1.8.x)

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

  • AVQFR_ - ошибки СКО
  • TR_ - ошибки обработки ответов СКО. Практически в 100% случаев обрабатываются на уровне Программной Кассы. Клиентская обработка не требуется. Данные ошибки могут фигурировать в лог-файлах
  • USB_ - ошибка взаимодействия по USB с устройством. При возникновении таких ошибок при работе с СКО, последнее помечается как неактивное и удаляется из списка доступных
  • CRT_ - ошибки чтения данных из сертификата в СКО. Данная ошибка не передается на текущий момент на клиентскую часть, т.к. при ошибке чтения данных СКО считается невалидным и не помещается в список доступных к использованию. Данные ошибки могут фигурировать в лог-файлах
  • AVTPCR_ - аналогично CRT_, но относится к аттрибутам устройства
  • TIN_ - ошибки валидации входных данных. Данные ошибки не должны возникать при валидной передаче данных и их обработка заключается в исправлении входных данных
  • TSRV_ - общие сервисные ошибки, должны обрабатываться в соответствии с их описанием
  • PR_ - ошибки связанные с взаимодействием с принтером. При возникновении данного типа ошибок на этапе фискализации передается поле op_data с фискальным чеком
  • TORD_ - ошибки работы с заказами в ресторанном режиме. В режиме ритейла данные ошибки отсутствуют

Более подробно об ошибках описано в описании методов и в разделе Ошибки данной документации.

Command Line Interface

Usage: tsrv [OPTIONS] [COMMAND]

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

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

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

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

  • create_sale
  • create_withdraw
  • 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": {  }
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Транспортный уровень

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

HTTP

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

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

По умолчанию HTTP сервер стартует на 0.0.0.0:1828, однако это можно поменяв, установив переменную окружения TSRV_ADDR в значение формата host:port

Все запросы совершаются методом 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": "init_session"
|   },
|   "data": null,
|   "type": "send"
| }

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

Возможен так же вариант взаимодействия по следующему URL методом POST: /tsrv/{address}/{action}.

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

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

> POST /tsrv/ik.service.app/init_session 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 запросе

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

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

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

  • Длина поля cashier не равна 0, иначе ошибка TIN_EMPTY_CASHIER
  • Длина поля cashier не превышает 20 символов, иначе ошибка TIN_CASHIER_LEN

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

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

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

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

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

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

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

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

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

  • Длина name не равна 0, иначе ошибка TIN_EMPTY_NAME
  • Длина name не превышает 128 символов, иначе ошибка TIN_NAME_LEN

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

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

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

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

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

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

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

Сервисы

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

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

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

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

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

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

ik.service.app

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

version

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

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

Примеры

Запрос:

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

Ответ (v2.x+)

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

Ответ (v1.8.x):

{
  "type": "send",
  "address": "version-msg",
  "reply_address": null,
  "data": {
    "version": "1.0.0"
  },
  "headers": null
}

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

request

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

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

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

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

print_delayed (v1.8.x)

Метод позволяет распечатать "отложенный" чек

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

{
  "id": String
}

ik.service.token

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

get_tokens

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

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

Возвращаемое значение (v1.8.x): Массив значений TokenInformation Возвращаемое значение (v1.8.x): Массив значений TokenInformation

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

Примеры

Запрос:

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

Ответ (v2.x):

{
  "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": "ООО \"АЙЭМЛЭБ\""
    }
  }
}

Ответ (v1.8.x):

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

get_token_by_serial

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

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

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

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

Возвращаемое значение (v1.8.x): TokenInformation Возвращаемое значение (v2.x): TokenInformation2

Примеры

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

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

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

Ответ (v2.x):

{
  "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",
  "reply_address": "example",
  "data": "BYN",
  "headers": {
    "token": "AVQ11031010703",
    "action": "get_cash_in_token"
  }
}

Ответ:

{
  "type": "send",
  "address": "example",
  "reply_address": null,
  "data": [
    {
      "cash": "0.00",
      "currency": "BYN"
    }
  ],
  "headers": null
}

next_cheque_number

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

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

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

Примеры

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

Запрос:

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

Ответ:

{
  "type": "send",
  "address": "example",
  "reply_address": null,
  "data": 5782,
  "headers": null
}

get_stored_documents

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

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

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

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

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

Примеры

Успех

Запрос:

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

Ответ:

{
   "type": "send",
   "address": "example",
   "reply_address": null,
   "data": 100,
   "headers": null
}

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

Запрос:

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

Ответ:

{
  "type": "error",
  "address": "example",
  "reply_address": null,
  "data": {
    "description": "сессия не авторизована (команда требует обязательной авторизации)",
    "name": "AVQFR_SESSION_NOT_AUTHORIZED"
  },
  "headers": null
}

get_oldest_document

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

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

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

Примеры

Успех

Запрос:

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

Ответ:

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

get_token_state

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

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

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

  • null если авторизация не пройдена
  • State, если авторизация пройдена

update_status

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

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

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

get_total_income

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

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

get_status

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

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

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

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

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

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

set_trade_point_name (v1.8.0)

Указание наименования торговой точки, для отображения на чеках.

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

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

print_prev_receipt

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

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

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

  • null - если чек не найден
  • Receipt - если чек найден

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

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

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

get_minmax_receipts (v1.8.x)

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

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

  • null - получение чеков в текущей смене
  • u16 - номер смены, из которой требуется получение номеров первого и последнего документа

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

  • AVQFR_SHIFT_IS_CLOSED - если передано null во входных данных и смена закрыта
  • AVQFR_SESSION_NOT_AUTHORIZED - если не пройдена авторизация в СКО
  • MinMaxReceipts - в случае успеха

get_receipt (v1.8.x)

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

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

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

  • null - если чек не найден
  • Receipt - если чек найден

Важно: Данный метод требует авторизации в СКО. В случае, если авторизация в СКО не пройдена будет возвращена ошибка AVQFR_SESSION_NOT_AUTHORIZED

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

ik.service.token.authority

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

authorize

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

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

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

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

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

Примеры

Успех

Запрос:

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

Ответ:

{
  "type": "send",
  "address": "example",
  "reply_address": null,
  "data": null,
  "headers": null
}

change_pin_code (v1.8.x)

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

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

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

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

Данный метод совершает следующие операции:

  1. Попытка совершить logout
  2. Авторизация по PUK-коду
  3. Смена PIN-кода
  4. logout

Примеры

Успех

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "reply_address": null,
  "data": {
    "pin": "16522",
    "puk": "17307748"
  },
  "headers": {
    "tokens.refresh": "true",
    "token": "AVQ11031010703",
    "action": "change_pin_code"
  }
}

Ответ:

{
  "type": "send",
  "address": null,
  "reply_address": null,
  "data": null,
  "headers": null
}

Ошибка (неверный PUK-код)

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "reply_address": null,
  "data": {
    "pin": "16522",
    "puk": "17307749"
  },
  "headers": {
    "token": "AVQ11031010703",
    "tokens.refresh": "true",
    "action": "change_pin_code"
  }
}

Ответ:

{
  "type": "error",
  "address": null,
  "reply_address": null,
  "data": {
    "description": "неверные данные для авторизации сессии (неверное значение PIN, PUK или REG)",
    "name": "AVQFR_BAD_KEY_AUTH_DATA",
  },
  "headers": null
}

Ошибка (неверная длина PUK-кода)

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "reply_address": null,
  "data": {
    "pin": "16522",
    "puk": "1730774"
  },
  "headers": {
    "token": "AVQ11031010703",
    "action": "change_pin_code",
    "tokens.refresh": "true"
  }
}

Ответ:

{
  "type": "error",
  "address": null,
  "reply_address": null,
  "data": {
    "description": "invalid code length. current: 7, required: 8",
    "name": "TIN_CODE_LEN"
  },
  "headers": null
}

Ошибка (неверная длина PIN-кода)

Запрос:

{
  "type": "send",
  "address": "ik.service.token.authority",
  "reply_address": null,
  "data": {
    "pin": "1652",
    "puk": "17307748"
  },
  "headers": {
    "token": "AVQ11031010703",
    "action": "change_pin_code",
    "tokens.refresh": "true"
  }
}

Ответ:

{
  "type": "error",
  "address": null,
  "reply_address": null,
  "data": {
    "description": "invalid code length. current: 4, required: 5",
    "name": "TIN_CODE_LEN"
  },
  "headers": null
}

logout

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

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

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

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

Примеры

Успех

Запрос:

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

Ответ:

{
  "type": "send",
  "address": "example",
  "reply_address": null,
  "data": null,
  "headers": null
}

ik.service.token.shift

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

open_shift

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

Входные данные (v1.8.x и v2.x): null

Входные данные (v2.х):

{
  "mode": "default" | "restaurant" | null
}

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

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

  • 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",
  "reply_address": "example",
  "data": null,
  "headers": {
    "action": "get_x_report",
    "token": "AVQ11169990670",
    "tokens.refresh": "true"
  }
}

print_x_report

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

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

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

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

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

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

Примеры

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

close_shift

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

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

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

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

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

Примеры

Успех

Запрос:

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

Ответ:

{
  "type": "send",
  "data": {
    "close_date": "2024-07-18 21:06:21",
    "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-18 17:07:22",
    "repr": {},
    "sales_count": 10,
    "serial_number": "AVQ11169990670",
    "tax_number": 193141246,
    "total_income": {
      "BYN": "149.00"
    },
    "uid": "D5CCDF029529C4E606A6E41E"
  }
}

get_z_report_copy

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

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

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

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

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

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

create_deposit

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

Возвращаемые данные (v1.8.x): Deposit Возвращаемые данные (v2.x): 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"
}

Ответ (v1.8.x):

{
  "type": "send",
  "address": null,
  "reply_address": null,
  "data": {
    "extra": null,
    "header": {
      "cashier": "Test",
      "company_name": "ИП Моров А.М.",
      "currency": "BYN",
      "date_time": "2021-09-25T14:07:07.523495+03:00",
      "device_id": 131010703,
      "number": 5918,
      "serial_number": "AVQ11031010703",
      "shift_number": 206,
      "tax_number": 191832203,
      "trade_point_name": null,
      "type_id": "deposit_v2",
      "uid": "0C7D6E36464C9F4A07CF108F"
    },
    "sum": "1.00"
  },
  "headers": null
}

create_withdraw

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

Возвращаемые данные (v1.8.x): Withdraw Возвращаемые данные (v2.x): 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"
}

Ответ (v2.x):

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

Ответ (1.8.x):

{
  "type": "send",
  "data": {
    "extra": null,
    "header": {
      "cashier": "Test",
      "company_name": "ООО \"АЙЭМЛЭБ\"",
      "currency": "BYN",
      "date_time": "2024-07-18 21:05:53",
      "device_id": 111600670,
      "number": 36,
      "serial_number": "AVQ11169990670",
      "shift_number": 3,
      "tax_number": 193141246,
      "trade_point_name": null,
      "type_id": "cashier_withdraw_v2",
      "uid": "5A8826C6EF3BF95006A6E41E"
    },
    "repr": {},
    "sum": "352.50"
  }
}

create_client_withdraw

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

Возвращаемые данные (v1.8.x): Client_Withdraw Возвращаемые данные (v2.x): 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"
}

Ответ (v2.x)

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

Ответ (v1.8.x):

{
  "type": "send",
  "address": null,
  "reply_address": null,
  "data": {
    "extra": null,
    "header": {
      "cashier": "Test",
      "company_name": "ИП Моров А.М.",
      "currency": "BYN",
      "date_time": "2021-09-25T14:08:57.072357+03:00",
      "device_id": 131010703,
      "number": 5919,
      "serial_number": "AVQ11031010703",
      "shift_number": 206,
      "tax_number": 191832203,
      "trade_point_name": null,
      "type_id": "client_withdraw_v2",
      "uid": "2636BF4D0E0E524F07CF108F"
    },
    "sum": "1.00"
  },
  "headers": null
}

create_sale

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

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

Возвращаемые данные (v1.8.x): Sale Возвращаемые данные (v2.x): 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": "Халва",
          "ref": "123414141124"
        },
        {
          "payment_type": "cash",
          "value": "20.00"
        }
      ],
      "cheque_discount": "2.00",
      "cheque_markup": "1.00",
      "tp_tax_number": 123456789
    }
  },
  "type": "send"
}

Ответ (v2.x):

{
	"type": "send",
	"data": {
		"header": {
			"uid": "C33C10DA6AC8ABF409894303",
			"number": 361,
			"date_time": "2025-03-01T17:54:27.644874+03:00",
			"shift_number": 78
		},
		"errors": null
	}
}

Ответ (v1.8.x):

{
  "type": "send",
  "data": {
    "change": "9.00",
    "header": {
      "cashier": "Test",
      "company_name": "ООО \"АЙЭМЛЭБ\"",
      "currency": "BYN",
      "date_time": "2024-07-18 21:01:16",
      "device_id": 111600670,
      "number": 35,
      "serial_number": "AVQ11169990670",
      "shift_number": 3,
      "tax_number": 193141246,
      "trade_point_name": null,
      "type_id": "sale_v2",
      "uid": "DCB2E337606B007206A6E41E"
    },
    "items": [
      {
        "item": {
          "code": {
            "code": "1845678901001"
          },
          "discount": "1.00",
          "markup": "1.00",
          "name": "Test Flat white",
          "price": "7.00",
          "quantity": "1.000",
          "section": {
            "code": 1,
            "name": "Тестовая секция"
          },
          "tax_rate": "tax20"
        },
        "values": {
          "discount": "100",
          "has_marking": false,
          "markup": "100",
          "sum": "700",
          "tax1": "117"
        }
      },
      {
        "item": {
          "code": {
            "code": "123132"
          },
          "discount": "1.00",
          "markup": "2.00",
          "name": "Не gtin товар",
          "price": "10.00",
          "quantity": "1.000",
          "section": null,
          "tax_rate": "tax10"
        },
        "values": {
          "discount": "100",
          "has_marking": false,
          "markup": "200",
          "sum": "1100",
          "tax1": "100"
        }
      }
    ],
    "payments": [
      {
        "name": "Халва",
        "payment_type": "cashless",
        "ref": "123414141124",
        "value": "6.00"
      },
      {
        "name": null,
        "payment_type": "cash",
        "ref": null,
        "value": "20.00"
      }
    ],
    "repr": {},
    "sub_totals": {
      "cheque_discount": "2.00",
      "cheque_markup": "1.00",
      "sum": "17.00",
      "taxes": [
        {
          "sum": "1.17",
          "tax_rate": "tax20"
        },
        {
          "sum": "1.00",
          "tax_rate": "tax10"
        }
      ]
    },
    "totals": {
      "discount": "2.00",
      "markup": "3.00",
      "sum": "18.00"
    },
    "tp_tax_number": 123456789
  }
}

create_money_back

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

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

Возвращаемые данные (v1.8.x): MoneyBack Возвращаемые данные (v2.x): 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"
}

Ответ (v2.x):

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

Ответ (v1.8.x):

{
  "type": "send",
  "data": {
    "header": {
      "cashier": "Test",
      "company_name": "ООО \"АЙЭМЛЭБ\"",
      "currency": "BYN",
      "date_time": "2024-07-18 20:46:13",
      "device_id": 111600670,
      "number": 25,
      "serial_number": "AVQ11169990670",
      "shift_number": 3,
      "tax_number": 193141246,
      "trade_point_name": null,
      "type_id": "money_back_v2",
      "uid": "D0A94EEE80104FC306A6E41E"
    },
    "items": [
      {
        "item": {
          "code": {
            "scan": [
              {
                "gtin": "123456789012"
              },
              {
                "unknown": "j239ej2je"
              },
              {
                "ukz": "midom0im20m03223d-2-d"
              }
            ]
          },
          "discount": "2.20",
          "markup": "1.50",
          "name": "Test Flat white",
          "price": "7.00",
          "quantity": "1.000",
          "section": {
            "code": 1,
            "name": "Тестовая секция"
          },
          "tax_rate": null
        },
        "values": {
          "has_marking": true,
          "sum": "630"
        }
      },
      {
        "item": {
          "code": {
            "service": "121"
          },
          "discount": "2.40",
          "markup": "1.10",
          "name": "Не gtin товар",
          "price": "10.00",
          "quantity": "1.000",
          "section": null,
          "tax_rate": null
        },
        "values": {
          "has_marking": false,
          "sum": "870"
        }
      }
    ],
    "payments": [
      {
        "name": null,
        "payment_type": "cash",
        "ref": null,
        "value": "10.00"
      },
      {
        "name": null,
        "payment_type": "cashless",
        "ref": null,
        "value": "5.00"
      }
    ],
    "repr": {},
    "totals": {
      "card": "5.00",
      "cash": "10.00",
      "other": "0.00",
      "sum": "15.00"
    }
  }
}

create_rollback

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

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

Возвращаемые данные (v1.8.x): Rollback Возвращаемые данные (v2.x): 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"
}

Ответ (v2.x):

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

Ответ (v1.8.x):

{
  "type": "send",
  "data": {
    "header": {
      "cashier": "Кассир",
      "company_name": "ООО \"АЙЭМЛЭБ\"",
      "currency": "BYN",
      "date_time": "2024-07-18 20:57:47",
      "device_id": 111600670,
      "number": 33,
      "serial_number": "AVQ11169990670",
      "shift_number": 3,
      "tax_number": 193141246,
      "trade_point_name": null,
      "type_id": "rollback_v2",
      "uid": "7ADA00F72937E57E06A6E41E"
    },
    "repr": {},
    "target_num": 32,
    "totals": {
      "card": "6.00",
      "cash": "0.00",
      "other": "0.00"
    }
  }
}

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

1

create_or_edit_order

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

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

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

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

ПолеТипПримечание
idstringID заказа. Макс. длина - 36 символов
cashierstringКассир, работающий с заказом
tableu32Номер столика
placeu32?Номер места за столиком, если имеется
itemsМассив ItemМассив товарных позиций
markupMoney?Надбавка, если имеется
discountMoney?Скидка, если имеется
prepaymentPayment?Предоплата с указанием способа. На момент оплаты будет преобразовано в тип оплаты "Предоплата"

Ответ:

ПолеТипПримечание
errorsErrors?Объект с ошибками, не связанными с СКО, если они возникали

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

{
  "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 передается идентификатор заказа для печати счёта

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

ПолеТипПримечание
errorsErrors?Объект с ошибками, не связанными с СКО, если они возникали

get_orders_information

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

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

Ответ:

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

Orders

ПолеТипПримечание
ordersMap<ID, OrderInformation>Словарь с информацией о заказами. Ключ - id заказа

OrderInformation

ПолеТипПримечание
sumMoneyСумма по заказу
bill_numberu32?Номер счёта по заказу, существует счёт по этому заказу

pay_order

Данные

Входные:

ПолеТипПримечание
order_idStringID заказа
paymentsМассив PaymentСпособы оплаты заказа. Перед началом фискализации в этот массив попадут данные из поля prepayment заказа. Тип способа оплаты у prepayment будет изменен на Prepayment
bundleBundle?Доп. данные для передачи в СКО

Bundle

ПолеТипПримечание
unique_idString?ID операции
user_dataString?base64 пользовательские данные
commentsComments?Комментарии
emailsМассив StringЭмейлы для отправки чека
trade_point_informationString?Доп. информация о торговой точке, если требуется

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

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

bill

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

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

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

{
  "id": "string"
}

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

Ответ:

{
  "type": "send",
  "data": {
    "number": 43,
    "errors": null
  }
}
  • number - сформированный / присвоенный номер счёта

Errors

ПолеТипПримечание
printingError?Ошибка печати
storageError?Ошибка работы с хранилищем данных

Error

ПолеТипПримечание
nameStringКод ошибки
descriptionStringТекст ошибки

Тип Version (v2.x)

{
  "version": "2.0.1",
  "kind": "tsrv",
  "build": "20250225.075316"
}
  • version - Версия ПК
  • kind - Тип ПК
  • build - Версия сборки API-слоя (tsrv)

Тип Version (v1.8.x)

{
   "version": String
}

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

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

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

Поля:

ПолеТипПримечание
extraRepr?Результаты отрисовки чека и прочие доп. данные
headerHeaderСодержит uid, number (номер док-та), date_time (в формате RFC3339), shift_number (номер смены)
errorsErrors?Ошибки, которые могли возникнуть после (!) фискализации

Repr

ПолеТипПримечание
esc_posString?Может отсутствовать. Содержит набор EscPos команд в base64 формате
textString?Может отсутствовать. Текстовое представление чека (без QR с УИ)
text_b64String?Может отсутствовать. Текстовое представление чека (без QR с УИ) в base64 формате
linkString?Может отсутствовать. Ссылка на чек

Тип PrintXReportReq

{
  "comments": Comments?
}

Тип CloseShiftRequest

{
  "comments": Comments?
}

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

Тип CloseShiftData

{
  "cashier" String?
}

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

  • cashier - имя кассира, закрывающего смену. Длина имени кассира не должны превышать 20 символов.

Пример:

{
  "cashier": "Администратор"
}

Тип 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

С версии 1.7.1

  • 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,
   "trade_point_name": String?
}
  • serial - серийный номер СКО
  • device_id - Регистрационный номер ПК в СККО
  • organization - наименование компании, на которую зарегистрировано СКО
  • tax_number - УНП СХ
  • pin_code_length - длина PIN-кода требуемого для авторизации
  • puk_code_length - длина PUK-кода требуемого для авторизации
  • operator_code - код Оператора Программной Кассы в соответствии с реестром
  • trade_point_name - наименование торговой точки (отсутствует, если не было установлено)

Пример:

{
  "device_id": 131010703,
  "operator_code": 5,
  "organization": "ИП Моров А.М.",
  "pin_code_length": 5,
  "puk_code_length": 8,
  "serial": "AVQ11031010703",
  "tax_number": 191832203,
  "trade_point_name": "Тестовая торговая точка"
}

Тип TokenInformation2

{
  "serial": String,
  "device_id": Int,
  "organization": String,
  "tax_number": Int,
  "pin_code_length": Int,
  "puk_code_length": Int,
  "operator_code": Int,
  "is_configured": Boolean,
  "is_compatible": Boolean,
  "version": String,
  "status": Status?,
  "server_config": ServerConfig?
}
  • serial - серийный номер СКО
  • device_id - Регистрационный номер ПК в СККО
  • organization - наименование компании, на которую зарегистрировано СКО
  • tax_number - УНП СХ
  • pin_code_length - длина PIN-кода требуемого для авторизации
  • puk_code_length - длина PUK-кода требуемого для авторизации
  • operator_code - код Оператора Программной Кассы в соответствии с реестром
  • is_configured - Сконфигурировано ли СКО
  • is_compatible - Совместимая ли версия ПК с СКО
  • version - Версия СКО
  • status - Статус СКО
  • server_config - Информация, получаемая с сервера

Status

{
  "last_update": String,
  "block_reasons": [ *String ]
}
  • last_update - Дата-время последнего обновления статуса
  • block_reasons - массив строк с описанием блокировок ПК.

ServerConfig

{
  "last_update": DateTime,
  "chw_max_value": Integer,
  "trade_point": {
    "addr": String,
    "name": String"
  },
  "organization": String
}
  • last_update - Дата-время последнего обновления статуса
  • chw_max_value - Максимальная сумма для операции Выдача в копейках
  • trade_point.addr - Адрес торговой точки
  • trade_point.name - Название торговой точки
  • organization - Название организации

Тип CashIn

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

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

Пример:

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

Тип OldestDocument

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

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

Пример:

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

Тип Pin

{
  "pin": String
}
  • pin - строковое представление PIN-кода

Пример:

{
  "pin": "16522"
}

Тип ChangePin

{
  "pin": String,
  "puk": String
}

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

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

Пример:

{
  "pin": "16522",
  "puk": "17307748"
}

Тип MinMaxReceipts

{
  min: u32,
  max: u32
}

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

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

Пример

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

Тип Receipt

{
  "type_id": deposit_v2 | cashier_withdraw_v2 | client_withdraw_v2 | money_back_v2 | rollback_v2 | sale_v2
}

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

  • type_id - в зависимости от типа чека могут быть следующие значения:
    • deposit_v2 - Внесение
    • cashier_withdraw_v2 - Изъятие
    • client_withdraw_v2 - Выдача
    • money_back_v2 - Возврат
    • rollback_v2 - Аннулирование
    • sale_v2 - Продажа
  • content - содержимое чека. В зависимости от type_id могут быть следующие значения:

Пример:

{
  "content": {
    "extra": null,
    "header": {
      "cashier": "Test",
      "company_name": "ИП Моров А.М.",
      "currency": "BYN",
      "date_time": "2021-10-05T15:27:36.803362+03:00",
      "device_id": 131010703,
      "number": 5981,
      "serial_number": "AVQ11031010703",
      "shift_number": 241,
      "tax_number": 191832203,
      "trade_point_name": null,
      "type_id": "deposit_v2",
      "uid": "7E047C2ABFC24FA207CF108F"
    },
    "sum": "1.00"
  },
  "type": "deposit"
}

Тип ReceiptRequest

{
  shift_number: u16?,
  number: u32
}

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

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

Пример

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

Тип Comments

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

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

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

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

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

Тип 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

Тип ZReportCopyRequest

{
   "number": u16,
}

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

  • number - номер смены

Тип Report

{
  uid: UID?,
  cashier: String?,
  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,
  counters: [ *ReportCounter ]
}
  • uid - УИ. В случае, если это Z-отчет - обязательное поле
  • cashier - Имя кассира в Z-отчете - опциональное поле, в X-отчете всегда null
  • device_id - Регистрационный номер ПК в СККО
  • tax_number - УНП
  • company_name - Наименование организации
  • open_date - Дата открытия смены
  • close_date - Дата закрытия смены, присутствует только в Z-отчете
  • number - Номер смены
  • first_sale_number - Номер первого документа продажи в смене
  • last_sale_number - Номер последнего документа продажи в смене
  • sales_count - количество документов продаж
  • currency_counters - Массив сменных счетчиков, содержит информацию по каждой валюте, по которой совершались операции в смене
  • total_income - накопленный оборот
  • additional.third_party - счетчики операций в пользу 3-х лиц

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

Пример:

{
  "type": "send",
  "data": {
    "close_date": "2024-07-18 11:17:03",
    "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-18 07:49:17",
    "repr": {},
    "sales_count": 10,
    "serial_number": "AVQ11169990670",
    "tax_number": 193141246,
    "total_income": {
      "BYN": "45.00"
    },
    "uid": "791261D74283114906A6E41E"
  }
}

Тип ReportCounter

"currency_counters": {
    "BYN": {
        "additional": {
            "third_party": {
                "rollback": {
                    "count": u16
                    "sum": Sum
                },
                "total": {
                    "count": u16
                    "sum": Sum
                }
            }
        },
        "client_withdraws": {
            "count": u16
            "sum": Sum
        },
        "deposits": {
            "count": u16
            "sum": Sum
        },
        "marking_si": {
            "count": u16
            "sum": Sum
        },
        "marking_ukz": {
            "count": u16
            "sum": Sum
        },
        "money_backs": {
            "card": Sum
            "cash": Sum
            "count": u16
            "other": Sum
            "sum": Sum
        },
        "rollbacks": {
            "card": Sum
            "cash": Sum
            "count": u16
            "other": Sum
            "sum": Sum
        },
        "sales": {
            "card": Sum
            "cash": Sum
            "count": u16
            "other": Sum
            "sum": Sum
        },
        "si_refund": {
            "count": u16
            "sum": Sum
        },
        "si_rollback": {
            "count": u16
            "sum": Sum
        },
        "ukz_refund": {
            "count": u16
            "sum": Sum
        },
        "ukz_rollback": {
            "count": u16
            "sum": Sum
        },
        "withdraws": {
            "count": u16
            "sum": Sum
        }
    }
}

  • currency_counters - валюта счетчика

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

  • sum - сумма продаж в валюте

  • card - сумма по карте

  • cash - сумма за наличные

  • other - сумма другими способами

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

  • total - сумма продаж в валюте в пользу 3х лиц

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

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

  • rollback - счетчик аннулирования

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

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

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

  • marking_si - счетчик продаж СИ

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

  • si_refund - счетчик возврата СИ

  • si_rollback - счетчик аннулирования СИ

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

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

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

Тип TaxRateSum

{
  tax_rate: TaxRate
  sum: Sum
}
  • tax_rate - ставка НДС
  • sum - сумма по ставке НДС

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

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

Пример:

{
  "tax_rate": "tax0",
  "sum": "0.00"
}

Тип TaxRate

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

  • tax0
  • tax10
  • tax20
  • tax25

Пример:

"tax0"

Тип TokenChequeHeader

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

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

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

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

Тип CalculatedItem

Товарная позиция с рассчитанными значениями

{
  "item": Item,
  "values": ItemCalculatedValues
}

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

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

Тип Items

{
  "id": String?,
  "price": Sum,
  "quantity": Quantity,
  "discount": Sum?,
  "markup": Sum?,
  "code": ItemCode,
  "section": ItemSection,
  "name": String,
  "tax_rate": TaxRate?
}

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

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

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

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

Тип 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,
  "ref": String?
}

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

  • payment_type - Тип платежа
  • name - Наименование платежа. Может отсутствовать
  • value - Сумма платежа
  • ref - Идентификатор платежного средства. Является опциональным полем и может быть использовано для идентификации RRN банковской транзакции, информации о банковском платеже, либо номере сертификата

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

Тип PaymentType

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

  • cash
  • cashless
  • other

Пример:

"cashless"

Тип Quantity

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

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

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

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

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

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

"12345.607"

Тип ChequeType

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

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

  • deposit_v2
  • cashier_withdraw_v2
  • client_withdraw_v2
  • rollback_v2
  • money_back_v2
  • sale_v2
  • z_report_v2

Пример:

"deposit_v2"

Тип ChequeHeader

{
  "type_id": ChequeType,
  "uid": UID,
  "device_id": u32,
  "serial_number": String,
  "cashier": String,
  "number": u32,
  "date_time": DateTime,
  "currency": Currency,
  "company_name": String,
  "tax_number": u32,
  "trade_point_name": String?,
  "shift_number": u16
}

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

  • type_id - тип чека
  • uid - УИ чека
  • device_id - Рег. номер ПК в СККО, в которой зарегистрирована операция
  • serial_number - Серийный номер СКО в котором зарегистрирована операция
  • cashier - кассир, который провел операцию
  • number - номер чека
  • date_time - дата и время фискализации чека
  • currency - валюта операции
  • company_name - название компании, которая провела операцию
  • tax_number - УНП компании, которая провела операцию
  • trade_point_name - наименование торговой точки, на которой проведена операция
  • shift_number - номер смены, в которой проведена операция

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

Тип ItemCalculatedValues

{
  "discount": Sum,
  "markup": Sum,
  "has_marking": bool,
  "sum": Sum,
  "tax1": Sum?
}

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

  • sum - рассчитанная сумма товарной позиции. Расчет происходит по формуле item.quantity * item.price - item.discount + item.markup
  • markup - надбавка по товарной позиции
  • discount - скидка по товарной позиции
  • tax1 - сумма по налоговой ставке за единицу тов. позиции (если есть)
  • has_marking - наличие маркировки на товарной позиции

Важно: При возврате, возвращаются только поля sum и has_marking.

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

Тип State

{
  "last_uid": UID,
  "shift_state": ShiftState?
}

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

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

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

Тип Status

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

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

  • unknown
  • active
  • blocked

Пример:

"active"

Тип Status

{
"type": "send",
"data": {
    "blockReasons": blockReasons?,
    "chwMaxValue": Int?,
    "companyName": String?,
    "isActive": Boolean?,
    "rn": Int?,
    "taxNumber": Int?,
    "tradeAddr": String?,
    "tradeName": Strint?
    }
}

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

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

Тип ShiftState

{
  "next_cheque_number": u32,
  "shift_number": u16,
  "shift_open_date": DateTime,
  "cash_in": Map<Currency, Sum>,
  "user_data": String?,
  "trade_point_information": String?
}

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

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

Доп поля доступные с версии 2.x:

  • user_data - Пользовательские данные в base64 формате
  • trade_point_information - Информация о торговой точке

Тип Deposit

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

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

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

Тип Withdraw

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

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

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

Тип Client_Withdraw

{
  "header": ChequeHeader,
  "sum": Sum,
  "id": String?
}

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

  • header - Заголовок чека
  • sum - сумма выдачи
  • id - идентификатор операции

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

Тип NewSumChequeRequest

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

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

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

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

Тип SumChequeData

{
  "header": TokenChequeHeader,
  "sum": Sum,
  "id": String?
}

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

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

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

Тип SaleRequest

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

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

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

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

Тип NewSale

{
  "header": TokenChequeHeader?,
  "items": [ *Item ],
  "payments": [ *Payment ],
  "cheque_discount": Sum,
  "cheque_markup": Sum,
  "tp_tax_number: u32?,
  "id": String?
}

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

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

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

Тип Sale

Сформированный чек продажи

{
  "header": ChequeHeader,
  "items": [ *CalculatedItem ],
  "payments": [ *Payment ],
  "change": Sum,
  "sub_totals": SaleSubTotals,
  "totals": SaleTotals,
  "tp_tax_number": u32?
}

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

Тип SaleSubTotals

{
  "sum": Sum,
  "cheque_discount": Sum,
  "cheque_markup": Sum
  "taxes": [ *TaxRateSum ]
}

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

  • sum - сумма под-итога (сумма всех товарных позиций с учетом скидок по тов. позициям)
  • cheque_discount - скидка по чеку
  • cheque_markup - надбавка по чеку
  • taxes - массив сумм в разрезе используемых в чеке НДС

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

Тип SaleTotals

{
  "sum": Sum,
  "discount": Sum,
  "markup": Sum
}

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

  • sum - сумма к оплате
  • discount - итоговая сумма скидки по чеку
  • markup - итоговая сумма надбавки по чеку

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

Тип NewMoneyBack

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

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

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

Тип NewMoneyBackRequest

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

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

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

Тип MoneyBackTotals

{
  "card": Sum,
  "cash": Sum,
  "other": Sum,
  "sum": Sum
}

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

  • card - сумма возврата безналичными
  • cash - сумма возврата наличными
  • other - сумма возврата другими способами
  • sum - сумма возврата

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

Тип MoneyBack

{
  "header": ChequeHeader,
  "items": [ *CalculatedItem ],
  "payments": [ *Payment ],
  "totals": MoneyBackTotals
}

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

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

Тип NewRollback

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

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

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

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

Тип NewRollbackRequest

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

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

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

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

Тип RollbackTotals

{
  "other": Sum,
  "cash": Sum,
  "card": Sum,
}

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

  • cash - сумма аннулирования наличными
  • card - сумма аннулирования безналичными
  • other - сумма аннулирования др. способами оплаты

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

Тип Rollback

{
  "header": ChequeHeader,
  "totals": RollbackTotals
}

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

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

Изменения от 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

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

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

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

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

  • удалено 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

Пример ответа со всеми переданными заголовками 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

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

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

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