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 является уникальным идентификатором чека и этот идентификатор можно использовать для отслеживания статуса печати чека.

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

Все параметры
{
	"type": "sell",
	"items": [
		{
			"type": "service"
			"name": "Доставка",
			"price": 100,
			"quantity": 1,
			"pay_type": "advance"
		},
		{
			"name": "Чипсы Lays",
			"price": 100,
			"quantity": 1
		},
		{
			"name": "Сухарики",
			"price": 50,
			"quantity": 2,
			"supplier_inn": "123456789",
            "supplier": {
                "name": "ООО Поставщик",
                "phone": "+123456789"
            },
            "agent": {
                "name": "ООО Агент",
                "INN": "3644065397",
                "address": "Тестовый адреса 16, офис 3",
                "phones": [ "+123456789" ]
            }
		}
	],
	"payments": [{
		"type": 0,
		"amount": 200
	}],
    "email": "client@mail.ru",
	"print": true,
    "caption": "Заказ #123456",
    "barcode": "V123456",
    "autoDelete": false,
	"agent_types": [ "payingAgent", "bankPayingAgent" ],
    "tax_system": "patent"
}

Описание:

Параметр Описание Тип данных Обязательно
type

Вид чека

sell – продажа

return – возврат продажи

String enum Нет
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 Нет
agent_types

Признак платежного агента. Можно передать как один, так и несколько значений

bankPayingAgent – банковский платежный агент

bankPayingSubagent – банковский платежный субагент

payingAgent – платежный агент

payingSubagent – платежный субагент

attorney – поверенный

commissionAgent – комиссионер

another – другой тип агента

String array Нет
tax_system

Система налогообложения для всего чека

main – ОСНО

usn6 – УСН 6

usn15 – УСН 15

envd – ЕНВД

eshn – ЕСХН

patent – Патент

String Нет

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

Параметр Описание Тип данных Обязательно
name Наименование позиции String Да
price Цена единицы позиции Double Да
quantity Количество Double Да
type

Тип позиции

commodity (по-умолчанию) – Товар

excise – Подакцизный товар

job – Работа

service – Услуга

gambling_bet – Ставка азартной игры

gambling_prize – Выигрыш азартнгой игры

lottery – Лотерейный билет

lottery_prize – Выигрыш лотереи

intellectual_activity – Предоставление результатов интерелектуальной деятельности 

payment – Платеж

agent_commission – Агентское вознаграждение 

another – Иной предмет расчета

String enum Нет, по-умолчанию используется commodity
pay_type

Тип оплаты

full_prepayment – Предоплата 100%

prepayment – Предоплата

advance – Аванс

full_payment (по-умолчанию) – Полный расчет

partial_payment – Частичный расчет и кредит 

credit – Передача в кредит 

credit_payment – Оплата кредита 

String enum Нет, по-умолчанию используется full_payment
supplier_inn ИНН поставщика String Нет
supplier

Объект с данными о поставщике

name - Наименование поставщика

phone - Номер телефона поставщика (если он один)

phones - Номера телефонов поставщика (массив телефонных номеров)

Object Нет
agent

Объект с данными об агенте

name- Наименование агента

INN - ИНН Агента

address - Адрес агента

phone - Номер телефона агента (если он один)

phones - Номера телефонов агента (массив телефонных номеров)

Object Нет

Примеры чеков

Чек предоплаты

Предоплата по заказу с оплатой наличными

{
    "type": "sell",
    "print": true,
    "items": [
        {
            "name": "Предоплата по заказу №123",
            "price": 100,
            "quantity": 1,
            "type": "service",
            "pay_type": "advance"
        }
    ],
    "payments": [
        {
            "type": 0,
            "amount": 100
        }
    ]
}


Статус чека

Возвращает информацию о чеке по его 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. Удаляем чек



Работает на системе OUTOFBOX.RU