Универсальный протокол для ККМ¶

UCRP-протокол представляет собой описание команд в формате JSON, передаваемые посредством http-запросов.
Все запросы передаются методом POST

Команды¶

Общие свойства¶

Запрос¶

Каждая команда обязательно содержит свойство Command, которое может принимать значения:

• OpenShift - открыть смену
• PrintReceipt - напечатать (зарегистировать) чек
• GetReport - снять отчет
• GetStatus - получить статус ККМ
• InOutCash - снятие/внесение наличных

Ответ¶

Объект ответа - это данные, которые ожидает GBS.Market после отправки команды на кассовый модуль

{
  "Result": 0,
  "Message":""
  "Data": {}
}

Каждый ответ должен содержать поля:

• Result - код ошибки. 0, если успешно.
• Message - сообщение о результате. В случае, если Result != 0, это сообщение будет показано пользователю
• Data - специфичные для каждой команды данные. Для некоторых команд может быть null

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

Запрос¶

{
  "Command": "OpenShift",
  "Cashier": {
    "Name": "Ivanov",
    "TaxId": "123456879012"
  }
}

Параметры:

• Command: команда на открытие смены
• Cashier - объект Кассира
  • Name - имя кассира
  • TaxId - ИНН

Ответ¶

{
  "Result":0,
  "Message":""
}

Напечатать чек¶

Команда для отправки чека в ККТ. Это может быть как регистрация фискального чека, так и печать нефискального чека.

Запрос¶

{
  "Command": "PrintReceipt",
  "ReceiptData": {
    "FiscalType": "Fiscal",
    "OperationType": "Sale",
    "TaxSystem": 0,
    "Cashier": {
      "Name": "Ivanov",
      "TaxId": "123456879012"
    },
    "Items": [
      {
        "Name": "Кофе МОНАРХ",
        "Barcode" : "",
        "Price": 1234.56,
        "Discount": 0.0,
        "Quantity": 1.23,
        "Comment": null,
        "VatIndex" : 0,
        "MarkingCode" : "",
      },
      {
        "Name": "Чай \"Липтон\"",
        "Barcode" : "",
        "Price": 7.89,
        "Discount": 0.0,
        "Quantity": 2,
        "Comment": null,
        "VatIndex" : 0,
        "MarkingCode" : "",
      }
    ],
    "Payments": [
      {
        "Sum": 1500.00,
        "Method": "Card"
      }
    ]
  }

}

Параметры:

• ReceiptData - данные чека
  • FiscalType - тип документа. Может принимать значения: Fiscal - фискальный чек, NonFiscal - нефискальный чек
  • OperationType - вид операции. Может принимать значения: Sale - продажа, Return - возврат (от покупателя)
  • TaxSystem - индекс системы налогообложения
  • Cashier - объект кассира
    • Name - имя кассира
    • TaxId - ИНН
  • Items - массив позиций в чеке. Каждая позиция имеет свойства:
    • Name - Название позиции
    • Barcode - штрихкод
    • Price - Цена 1 шт (без скидки)
    • Discount - Скидка (абсолютная)
    • Quantity - кол-во
    • Comment - комментарий
    • VatIndex - индекс налоговой ставки (НДС)
    • MarkingCode - код маркировки
  • Payments - массив платежей. Каждый платеж имеет свойства:
    • Sum - сумма платежа
    • Method - тип метода оплаты. Может принимать значения: Cash - наличными, Card - картой, Bank - безналично (банковский платеж), Electronically - электронно (перевод, СБП и т.п.), Credit - кредитом (оплата в долг), Prepaid - предоплата

Ответ¶

{
  "Result":0,
  "Message":""
  "Data": {
    "ReceiptId": "9876543210"
  }
}

Объект Data содержит свойства:

• ReceiptId - номер/идентификатор чека, зарегистирована в ККМ

Снять отчет¶

Запрос¶

{
  "Command": "GetReport",
  "ReportType": "ZReport",
  "Cashier": {
    "Name": "Ivanov",
    "TaxId": "123456879012"
  }
  
}

Параметры:

• ReportType - тип отчета. Может принимать значения:
  • XReport - снять отчет без гашения
  • ZReport - снять отчет с гашением (и закрыть смену)
• Cashier - объект кассира
  • Name - имя
  • TaxId - ИНН

Ответ¶

{
  "Result":0,
  "Message":""
  "Data":{
    "ReportData": "Дневной отчет без гашения\n\nПродажи: 100.00\nВозвраты: 0.00"
  }
}

Ответ содержит свойство ReportData, которое содержит текст отчета. Если необходимо, чтобы отчет был напечатан GBS.Market, свойство должно быть заполнено.
Если свойство null или пустое, то отчет в GBS.Market не будет печататься.

Снять/внести наличные¶

Запрос¶

{
  "Command": "InOutCash",
  "Sum": 12345.56,
  "Cashier": {
    "Name": "Ivanov",
    "TaxId": "123456879012"
  }
}

Параметры:

• Sum - сумма. Если положительная - внесение. Отрицательная - выемка
• Cashier - объект кассира

Ответ¶

{
  "Result":0,
  "Message":""
}

Получение статуса¶

Команда на получение состояния кассы

Запрос¶

{
  "Command": "GetStatus"
}

Ответ¶

{
  "Result": 0,
  "Message":""
  "Data": {
    "ShiftStatus":"Open",
    "ShiftNumber":1,
    "ShiftOpeningDate": "2001-01-01T00:00:00",
    "ReceiptState":"Close",
    "ReceiptNumber":123,
    "KkmModel":"Atol 30F",
    "DriverVersion":"10.0"
  }
}

Объект Data имеет свойства:

• ShiftStatus - статус смены. Может принимать значения:
  • Open - открыта
  • Close - закрыта
  • OpenMore24Hours - открыта более 24 часов, работа кассы невозможна
• ShiftNumber - номер текущей смены
• ShiftOpeningDate - дата и время открытия смены
• ReceiptState - состояние чека
  • Open - открыт. В этом случае будет попытка отмены чека
  • Close - закрыт
• ReceiptNumber - номер текущего чека
• KkmModel - модель кассы
• DriverVersion - версия драйвера

Коды ответов¶

GBS.Market может по-разному реагировать, в зависимости от кода ответа.
Например, если ККМ вернет код ответа 5 (смена превышает 24 часа) - будет предложено закрыть смену и попробовать снова.
В большинстве случаев будет отображено сообщение пользователю, содержащееся в свойстве Message объекта ответа.

Список кодов¶

• 0 - операция выполнена
• 1 - нет связи с устройством
• 2 - порт устройства занят
• 3 - техническая неисправность ККМ, необходима диагностика в сервисном центре
• 4 - нет бумаги
• 5 - смена превышает 24 часа
• 6 - недопустимый индекс способа оплаты
• 7 - некорректные данные, переданные в ККМ
• 8 - открыта крышка принтера
• 9 - превышен срок хранения офлайн документов
• 10 - некорректное значение даты/времени в ККМ
• 999 - недокументированная ошибка