Outofbox.54-FZ : Протокол обмена

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

После включения устройства в вашу локальную сеть, рекомендуется выдать ему статический IP адрес и выдать локальное DNS имя (если это возможно).

Система является асинхронной, нет гарантии, что чек будет отпечатан немедленно, так как в один момент времени кассовый аппарат можем работать только с одним чеком. Все чеки попадают в очередь на печать и будут отпечатаны по принципу FIFO (first in first out). Также система отдает более высокий приоритет чекам от кассира, чтобы не задерживать покупателя. Онлайн чеки идут с меньшим приоритетом. Весь процесс отслеживания описан в соответствующем разделе.

Печать чека продажи

POST
/_api/receipts

В тело запроса надо передать json объект следующего вида:

Минимальные параметры
{
	"items": [{
		"name": "Чипсы Lays",
		"price": 100,
		"quantity": 1
	}, {
		"name": "Сухарики",
		"price": 50,
		"quantity": 2
	}],
	"payments": [{
		"type": 0,
		"amount": 200
	}]
}

В случае успешного приема чека, будет выдан HTTP код ответа 200, а в теле документа будет json объект чека:

{
    "receipt": {
        "uuid": <UUID>,
        "status": "PENDING",
        ...
    }
}

uuid является уникальным идентификатором чека и этот идентификатор можно использовать для отслеживания статуса печати чека.

Список всех доступных параметров с их описанием:

Все параметры
{
	"items": [{
		"name": "Чипсы Lays",
		"price": 100,
		"quantity": 1
	}, {
		"name": "Сухарики",
		"price": 50,
		"quantity": 2
	}],
	"payments": [{
		"type": 0,
		"amount": 200
	}],
    "email": "client@mail.ru",
	"print": true,
    "caption": "Заказ #123456",
    "barcode": "V123456",
    "autoDelete": false
}

Описание:

Название Описание Тип данных Обязательно
items Массив список позиций чека с указанием наименование, цены за единицу и общего количества. Array Да
payments

Массив оплат по чеку. 

Каждый элемент массива – объект с ключами type и amount

type – тип платежа. Соответствует номеру платежа из кассового аппарата. 0 – как правило, наличные

amount  – сумма данного способа платежа

Сумма всех платежей должна соответствовать общей стоимости из массива items

Array Да
email Email клиента, куда будет отправлен электронный чек String Нет
print

Если задан email клиента, то данный параметр управляет печатью чека на бумажном носителе.

Если true, то бумажный чек будет отпечатан

Если false, то бумажный чек не будет отпечатан

В случае, если email не задан, то данный параметр всегда будет принимать значение true

Boolean Нет
caption

Подпись чека.

Если задано это значение, то строка будет отпечатана в начале чека.

String Нет
barcode

Штрихкод чека.

Если задано это значение, то в начале чека будет отпечатан штрихкод,

в котором будет закодирована значение в формате CODE128

String Нет
autoDelete

Параметр для автоудаления. Если не планируется использовать отслеживание статуса чека, то можно передать сюда true и такой чек будет удален сразу же после успешной печати.

По-умолчанию false

Boolean Нет

Статус чека

Возвращает информацию о чеке по его UUID

GET
/_api/receipts/{uuid}


{
    "receipt": {
        "uuid": <UUID>,
        "status": "PENDING"
    }
}

Удаление чека

Рекомендуется удалить чек после того, как мы отследили его статус, чтобы он удалился из системы немедленно. Для этого можно послать следующий DELETE запрос:

DELETE
/_api/receipts/{uuid}

В случае успешного удаления чека код ответа будет HTTP 204

Отслеживание статуса чека

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

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

  1. Отправляем чек на печать, получаем его UUID
  2. Используя этот UUID запрашиваем статус чека до тех пор, пока поле status не примет значение SUCCESS или ERROR.
  3. Если status чека равен ERROR, то в поле errorMessage можно посмотреть текст ошибки
  4. Удаляем чек