Протокол обмена

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

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

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

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

`POST`	`/_api/receipts`

Минимальные параметры

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

{
  "items": [
    {
      "name": "Чипсы",
      "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": "Чипсы",
      "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.

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

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

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

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

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

Минимальные параметры​

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

Описание параметров:​

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

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

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

Статус чека​

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

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