1 Использование API
2 Идентификация заказа и сессии
3 Транспорт и протокол
4 Формат сообщений
5 Типы сообщений
6 Коды ошибок и их описание
- 6.1 Объект ошибки
7 Объект заказа
8 Аутентификация
- 8.1 Формат запроса
- 8.2 Формат ответа
9 Проверить соединение
- 9.1 Формат запроса
- 9.2 Формат ответа
10 Создать заказ
- 10.1 Формат запроса
- 10.2 Формат ответа
11 Получить заказ
- 11.1 Формат запроса
- 11.2 Формат ответа
12 Применить скидку мерчанта
- 12.1 Формат запроса
- 12.2 Формат ответа
13 Обновить статус заказа
- 13.1 Формат ответа
14 Закрыть заказ
- 14.1 Формат запроса
- 14.2 Формат ответа
15 Получить все заказы
- 15.1 Формат запроса
- 15.2 Формат ответа
16 Сохранить настройки кассы
- 16.1 Формат запроса
- 16.2 Формат ответа
17 Получить настройки кассы
- 17.1 Формат запроса
- 17.2 Формат ответа

Использование API

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

Идентификация заказа и сессии

Идентификаторами заказа являются поля id и merchantOrderId.

Название поля	Описание

Название поля	Описание
`id (UUID)`	Идентификатор в системе SWiP. Касса не должна его ставить. Касса создает заказ, посылая объект заказа (Order). Обратно приходит так же объект Order c установленным полем id. Дальше это поле используется в запросах GET.
`merchantOrderId`	Идентификатор заказа у мерчанта.
`otp (one time paid)`	Дополнительное поле для идентификации заказа при оплате через SELFIETOPAY (STP).

Идентификатором сессии является поле sessionCode.

Название поля	Описание

Название поля	Описание
`sessionCode`	Идентификатор сессии (текстовое значение зашифрованное в QR-коде). Если касса работает в режиме ресторана, то QR-код берется из ответа сервера на запрос создания заказа.

Транспорт и протокол

В качестве транспорта используется TCP/IP протокол. Сообщения кодируются в формат Google Protobuf.

Спецификация сообщений находится здесь.

Формат сообщений

Сообщения состоят из заголовка и тела.

header - 22 байта:
- bodyLength - 4 байта
- messageId - 2 байта
- reserved - 16 байт (будет заполнено нулями, зарезервировано для будущего использования)
body

Логика обработки сообщения следующая:

Читаем 22 байта из сокета;
Определяем bodyLength и messageId;
Читаем <bodyLength> байт из потока;
Вызываем соответствующий обработчик protobuf для декодирования сообщения.

При этом в реализации нужно добавить проверку на длину сообщения. Если длина больше определенной длины, например 10Mb, то возможно сообщение неправильно прочитано (не сначала). Также при декодировании с помощью protobuf может произойти ошибка из-за неправильного формата. В обоих случаях необходимо делать реконнект.

Типы сообщений

Каждое сообщение имеет свой MessageId, который будет передаваться в типе сообщения. Ниже представлен список сообщений и их идентификаторы.

Название сообщения	Идентификатор сообщения

Название сообщения	Идентификатор сообщения
ERROR	1
CASH_LOGIN_REQUEST	12
LOGIN_RESPONSE	11
CASH_CREATE_ORDER_REQUEST	200
CASH_CREATE_ORDER_RESPONSE	201
CASH_GET_ORDER_REQUEST	210
CASH_GET_ORDER_RESPONSE	211
CASH_GET_ORDER_LIST_REQUEST	220
CASH_GET_ORDER_LIST_RESPONSE	221
CASH_CLOSE_ORDER_REQUEST	230
CASH_CLOSE_ORDER_RESPONSE	231
CASH_ORDER_STATUS_UPDATED	240
CASH_SAVE_SETTING_REQUEST	250
CASH_SAVE_SETTING_RESPONSE	251
CASH_GET_SETTING_REQUEST	260
CASH_GET_SETTING_RESPONSE	261
HEARTBEAT_REQUEST	0
HEARTBEAT_RESPONSE	2
CASH_ORDER_APPLY_MERCHANT_DISCOUNT_REQUEST	270
CASH_ORDER_APPLY_MERCHANT_DISCOUNT_RESPONSE	271

Коды ошибок и их описание

Код ошибки	Описание

Код ошибки	Описание
1	INTERNAL SERVER ERROR Внутренняя ошибка сервера.
2	AUTHENTICATION ERROR Неудачная аутентификация.
4	ACCESS DENIED Доступ запрещен.
5	VALIDATION FAILED Некорректная валидация.
6	ILLEGAL STATE Ошибка неправильного состояния текущей операции.
7	METHOD NOT SUPPORTED Метод не поддерживается.
8	DUPLICATE Дублицирование данных.
9	NOT FOUND Ресурс не найден.
10	UNSUPPORTED MESSAGE Неподдерживаемое сообщение.
11	ORDER FLOW VIOLATION Нарушение процесса обработки заказа.
12	SMS CODE EXPIRED Истек срок действия СМС-кода.
13	OPERATION TIMED OUT Истекло время ожидания операции.
14	DOESNT MATCH Несовпадение данных.
15	PAYMENTS BLOCKED Платежи заблокированы.
16	TOKEN EXPIRED Истек срок действия JWT токена.
17	JWT TOKEN ERROR Ошибка процессинга токена.
18	CONCURRENT PAYMENT ERROR Ошибка из-за осуществления параллельных платежей.
19	BANK PAYMENT ERROR Ошибка оплаты банка.
20	PAYMENT CARD BLOCKED Платежная карта заблокирована.
21	ACCOUNTING ERROR Ошибка в расчетах.
22	REQUEST LIMIT EXCEEDED Превышен лимит количества запросов.
23	EXTERNAL SYSTEM ERROR Внешняя ошибка системы.
24	CASHBACK PAYMENT ERROR Ошибка при оплате кэшбэком.
25	OPERATION IN PROGRESS Операция находится в процессе выполнения.
26	CUSTOMER DUPLICATE PIN Дублицирование ПИН-кода клиента.
27	REVERSE UNAVAILABLE Отмена оплаты недоступна.
28	ORDER ALREADY EXISTS Заказ уже существует.
29	ORDER ALREADY REFUNDED Возврат по заказу уже выполнен.
30	ORDER ALREADY CONFIRMED Подтверждение оплаты заказа уже выполнено.
31	ORDER NOT PAID Ордер не оплачен.
32	EXCESS TOTAL AMOUNT Попытка вернуть сумму превышающую сумму заказа.

Объект ошибки

Если при выполнении запроса произошла ошибка, вернется следующий объект:

 message Error {
    string requestId = 1;			// уникальный идентификатор сообщения в сокет канале
    string description = 2;	        // описание ошибки
    int32 errorCode = 3;            // код внутренней ошибки SWiP    		   
}

Объект заказа

Объект заказа (Order) содержит всю информацию о заказе, актуальную на текущий момент времени. Он формируется при создании заказа и приходит в ответ на некоторые запросы.

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

* поля, которые должна проставлять касса.

Параметр	Тип	Описание

Параметр	Тип	Описание
`sessionCode`*	UUID	Код сессии, генерируемый клиентом Cash Gate, в частности QR-код (только в режиме фастфуда или магазина).
`shortCode`	string	Альтернатива QR-кода.
`id`	string	Идентификатор ордера в системе SWiP.
`customerId`	string	Идентификатор клиента оплатившего заказ. Значение присутствует после закрытия заказа.
`merchantId`	string	Идентификатор мерчанта в системе SWiP.
`merchantName`	string	Название мерчанта.
`merchantProfileImageId`	string	Идентификатор изображения в профиле мерчанта.
`merchantCategory`	string	Описание сферы деятельности мерчанта.
`merchantOrderId`*	string	Идентификатор заказа в системе мерчанта.
`merchantOrderNumber`*	string	Номер заказа в системе мерчанта (обычно печатается в чеке).
`merchantStore`	string	Идентификатор торговой точки.
`merchantCash`	string	Идентификатор кассы или группы касс.
`merchantCashierId`*	string	Идентификатор кассира.
`merchantCashier`*	string	Имя кассира.
`saleDate`*	long	Время заказа (в миллисекундах с 01.01.1970).
`total`*	double	Сумма покупки с учетом скидки.
`totalOriginal`*	double	Сумма покупки без скидки.
`cashback`	double	Сумма кэшбэка.
`discount`	double	Сумма скидки.
`swipDiscount`	double	Скидка (сумма баллов и дисконта), которую предоставляет SWiP.
`purchases`	repeated Purchase	Список покупок.
`orderStatus`	OrderStatus	Статус заказа. Возможные значения: OPEN, CLOSED, LOYALTY_CALCULATION
`paymentMethod`	PaymentMethod	Способ оплаты. Возможные значения: CARD, CREDIT, CASH.
`otp`	string	Дополнительный идентификатор заказа (one time paid). Необходим для включения камеры.
`paid`	double	Сумма, оплаченная клиентом через приложение. Значение присутствует после закрытия заказа.
`unconfirmed`	double	Сумма, оплаченная клиентом через приложение, но не подтвержденная кассой (paid>=unconfirmed).
`closeAmount`*	double	Сумма, которую касса считает к закрытию заказа. Значение присутствует после закрытия заказа.
`availablePoints`	int32	Баллы, доступные для списания.
`pointsRate`	double	Доля рубля в 1 балле.
`pointsAsDiscount`	double	Скидка, полученная при списании баллов.
`awardPoints`	int32	Количество заработанных баллов в этом заказе.
`withdrawPoints`	int32	Количество баллов, которые списываются в этом заказе.
`paymentWay`	PaymentWay	Способ оплаты. Возможные значения: APP, STP.
`apiVersion`	integer	Версия API, по которой оплачен заказ.
`slip`	string	Форматированный текст (80 символов в ширину) с банковской информацией о платеже.
`authorizationCode`	string	Авторизационный код платежа.
`terminalNo`	string	Номер банковского терминала.
`pan`	string	Маскированный номер карты.
`rrn`	string	Уникальный идентификатор банковской транзакции, который назначается банком Эквайрером при инициализации платежа.
`error`	string	Последняя ошибка при оплате заказа.
`merchantDiscount`	double	Скидка, которую предоставляет мерчант.
`discountCard`	string	Уникальный идентификатор дисконтной карты.

Purchase	Тип	Описание

Purchase	Тип	Описание
`id`	string	Идентификатор товара в системе SWiP
`productId`	string	Артикул (идентификатор товара).
`name`	string	Название товара.
`quantity`	double	Количество (штук, килограмм, литров).
`amount`	double	Стоимость (price * quantity).
`price`	double	Цена.
`discount`	double	Сумма скидки.
`merchantDiscount`	double	Скидка, которую предоставляет мерчант.
`unit`	string	Единицы измерения.

Пример объекта Order

message Order {
    string sessionCode = 1;
    string shortCode = 2;
    string id = 3;
    string customerId = 4;
    string merchantId = 5;
    string merchantName = 6;
    string merchantProfileImageId = 7;
    string merchantCategory = 8;
    string merchantOrderId = 9;
    string merchantOrderNumber = 10;
    string merchantStore = 11;
    string merchantCash = 12;
    string merchantCashierId = 13;
    string merchantCashier = 14;
    int64 saleDate = 15;
    double total = 16;
    double totalOriginal = 17;
    double cashback = 18;
    double discount = 19;
    double swipDiscount = 20;
    repeated Purchase purchases = 21;
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;
    PaymentMethod paymentMethod = 33;
    string otp = 34;
    int32 apiVersion = 35;
    string slip = 36;
    string rrn = 37;
    string authorizationCode = 38;
    string terminalNo = 39;
    string pan = 40;
    double merchantDiscount = 41;
    string discountCard = 42;
}

Пример объекта Purchase

message Purchase {
    string id = 1;
    string productId = 2;
    string name = 3;
    double quantity = 4;
    double amount = 5;
    double price = 6;
    double discount = 7;
    double merchantDiscount = 8;
    string unit = 9;
}

Аутентификация

Требуется для идентификации в системе SWiP.

Формат запроса

Для аутентификации необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`merchantId`	string, обязательный	Уникальный идентификатор мерчанта в системе SWiP.
`token`	string, обязательный	Токен для аутентификации. Берется из личного кабинета мерчанта в SWiP.
`storeId`	string, обязательный	Уникальный идентификатор магазина в системе SWiP.
`cashId`	string, обязательный	Уникальный идентификатор кассы в системе SWiP.
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.

Пример сообщения запроса

message CashLoginRequest {
    string merchantId = 1;
    string token = 2;
    string storeId = 3;
    string cashId = 4;
    string requestId = 5;
}

Формат ответа

В ответ приходит идентификатор сообщения и объект с информацией об обновлениях программного обеспечения для STP-устройства, если они есть.

Пример сообщения ответа

message LoginResponseMessage {
    string requestId = 1;
    UpdateInfo updateInfo = 2;
}

message UpdateInfo {
    string version = 1;
    string url = 2;
    bool force = 3;
}

Проверить соединение

Выполняется, чтобы убедиться, что соединение с сервером установлено.

Формат запроса

Для проверки соединения необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`deviceId`	int32, необязательный	Идентификатор S2P-устройства.

Пример сообщения запроса

message HeartBeatRequest {
    string requestId = 1;
    int64 deviceId = 2;
}

Формат ответа

В ответ приходит идентификатор сообщения.

Пример сообщения ответа

1
2
3

message HeartbeatResponse {
    string requestId = 1;
}

Создать заказ

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

Формат запроса

Для создания заказа необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`sessionCode`	string, обязательный	Код сессии, генерируемый клиентом Cash Gate, в частности QR-код.
`merchantOrderId`	string, обязательный	Уникальный идентификатор заказа у мерчанта.
`merchantOrderNumber`	string, обязательный	Идентификатор чека у мерчанта.
`merchantCashier`	string, обязательный	Имя кассира.
`merchantCashierId`	string, обязательный	Идентификатор кассира.
`saleDate`	long, обязательный	Время продажи.
`total`	double, обязательный	Сумма покупки с учетом скидки.
`totalOriginal`	double, обязательный	Сумма без скидки.
`purchases`	repeated Purchase, обязательный	Список покупок.

Пример сообщения запроса

message CashCreateOrderRequest {
    string requestId = 1;
    NewOrder newOrder = 2;
}

message NewOrder {
    string sessionCode = 1;
    string merchantOrderId = 2;
    string merchantOrderNumber = 3;
    string merchantCashierId = 4;
    string merchantCashier = 5;
    sint64 saleDate = 6;
    double total = 7;
    double totalOriginal = 8;
    repeated Purchase purchases = 9;
}

Формат ответа

В ответ на запрос придет тот же заказ с проставленными полями: id - SWiP orderId, sessionCode. Если sessionCode был отправлен пустым, то обратно вернется заполненное поле, его надо напечатать в пречеке или показать на экране (кассовом) покупателю.

Пример сообщения ответа

message CashCreateOrderResponse {
    string requestId = 1;
    Order order = 2;
}

message Order {
    string sessionCode = 1;                       // текстовое значение QR-кода
    string shortCode = 2;                         // альтернатива QR-кода
    string id = 3;                                // идентификатор заказа в системе SWiP
    string customerId = 4;
    string merchantId = 5;                        // идентификатор мерчанта
    string merchantName = 6;                      // название мерчанта
    string merchantProfileImageId = 7;            // идентификатор изображения в профиле мерчанта
    string merchantCategory = 8;                  // категория мерчанта
    string merchantOrderId = 9;                   // уникальный идентификатор заказа у мерчанта
    string merchantOrderNumber = 10;              // идентификатор чека у мерчанта
    string merchantStore = 11;                    // идентификатор торговой точки
    string merchantCash = 12;                     // идентификатор кассы или группы касс
    string merchantCashierId = 13;                // идентификатор кассира
    string merchantCashier = 14;                  // имя кассира
    sint64 saleDate = 15;                         // дата продажи
    double total = 16;                            // сумма (с учетом скидки, если таковая есть у клиента)
    double totalOriginal = 17;                    // сумма (без учета скидки)	
    double cashback = 18;                         // размер кэшбэка
    double discount = 19;                         // сумма скидки
    double swipDiscount = 20;                     // скидка (сумма баллов и дисконта), которую предоставляет SWiP
    repeated Purchase purchases = 21;             // список покупок (товары в чеке)
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;                 // статус заказа
    PaymentMethod paymentMethod = 33;             // способ оплаты
    int32 apiVersion = 34;                        // версия API
    string otp = 35;                              // дополнительный идентификатор заказа (one time paid)
    string slip = 36;
    string rrn = 37;                              // уникальный идентификатор банковской транзакции
    string authorizationCode = 38;                // авторизационный код платежа
    string terminalNo = 39;                       // номер банковского терминала
    string pan = 40;                              // маскированный номер карты
    double merchantDiscount = 41;                 // скидка, предоставляемая мерчантом
    string discountCard = 42;                     // идентификатор дисконтной карты
}

Получить заказ

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

Формат запроса

Для получения текущего состояния заказа необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`orderId`	string, обязательный	Уникальный идентификатор заказа в системе SWiP.

Пример сообщения запроса

message CashGetOrderRequest {
    string requestId = 1;
    string orderId = 2;
}

Формат ответа

В ответ приходит объект заказа в актуальном статусе.

Пример сообщения ответа

message CashGetOrderResponse {
    string requestId = 1;
    Order order = 2;
}

message Order {
    string sessionCode = 1;
    string shortCode = 2;
    string id = 3;
    string customerId = 4;
    string merchantId = 5;
    string merchantName = 6;
    string merchantProfileImageId = 7;
    string merchantCategory = 8;
    string merchantOrderId = 9;
    string merchantOrderNumber = 10;
    string merchantStore = 11;
    string merchantCash = 12;
    string merchantCashierId = 13;
    string merchantCashier = 14;
    int64 saleDate = 15;
    double total = 16;
    double totalOriginal = 17;
    double cashback = 18;
    double discount = 19;
    double swipDiscount = 20;
    repeated Purchase purchases = 21;
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;
    PaymentMethod paymentMethod = 33;
    int32 apiVersion = 34;
    string otp = 35;
    string slip = 36;
    string rrn = 37;
    string authorizationCode = 38;
    string terminalNo = 39;
    string pan = 40;
    double merchantDiscount = 41;
    string discountCard = 42;
}

Применить скидку мерчанта

Применяет скидку мерчанта для заказа в статусе LOYALTY_CALCULATION.

Формат запроса

Для применения скидки мерчанта необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`orderId`	string, обязательный	Уникальный идентификатор заказа в системе SWiP.
`merchantDiscount`	double, обязательный	Скидка, предоставляемая мерчантом.
`total`	double, обязательный	Общая сумма заказа.
`purchases`	repeated Purchase, обязательный	Список покупок.

Пример сообщения запроса

message CashOrderApplyMerchantDiscountRequest {
    string requestId = 1;
    string orderId = 2;
    double merchantDiscount = 3;
    double total = 4;
    repeated Purchase purchases = 5;
}

message Purchase {
    string id = 1;
    string productId = 2;
    string name = 3;
    double quantity = 4;
    double amount = 5;
    double price = 6;
    double discount = 7;
    double merchantDiscount = 8;
    string unit = 9;
}

Формат ответа

В ответ приходит объект заказа в актуальном статусе.

Пример сообщения ответа

message CashOrderApplyMerchantDiscountResponse {
    string requestId = 1;
    Order order = 2;
}

message Order {
    string sessionCode = 1;
    string shortCode = 2;
    string id = 3;
    string customerId = 4;
    string merchantId = 5;
    string merchantName = 6;
    string merchantProfileImageId = 7;
    string merchantCategory = 8;
    string merchantOrderId = 9;
    string merchantOrderNumber = 10;
    string merchantStore = 11;
    string merchantCash = 12;
    string merchantCashierId = 13;
    string merchantCashier = 14;
    int64 saleDate = 15;
    double total = 16;
    double totalOriginal = 17;
    double cashback = 18;
    double discount = 19;
    double swipDiscount = 20;
    repeated Purchase purchases = 21;
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;
    PaymentMethod paymentMethod = 33;
    int32 apiVersion = 34;
    string otp = 35;
    string slip = 36;
    string rrn = 37;
    string authorizationCode = 38;
    string terminalNo = 39;
    string pan = 40;
    double merchantDiscount = 41;
    string discountCard = 42;
}

Обновить статус заказа

После оплаты заказа приходит сообщение с обновленным статусом оплаты на сервере SWiP.

Формат ответа

Пример сообщения

message CashOrderStatusUpdated {
    string requestId = 1;
    string orderId = 2;
    double totalOriginal = 3;
    double total = 4;
    double paid = 5;
    double unconfirmed = 6;
    double refunded = 7;
    OrderStatus orderStatus = 8;
    string discountCard = 9;
    double swipDiscount = 10;
}

Закрыть заказ

Сообщение вызывает закрытие заказа.

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

Формат запроса

Для закрытия заказа необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`orderId`	string, обязательный	Уникальный идентификатор заказа в системе SWiP.
`amountToClose`	double, обязательный	Сумма, которую касса передает к закрытию заказа.

Пример сообщения запроса

message CashCloseOrderRequest {
    string requestId = 1;
    string orderId = 2;
    double amountToClose = 3;
}

Формат ответа

В ответ приходит объект заказа в актуальном статусе.

Пример сообщения ответа

message CashCloseOrderResponse {
    string requestId = 1;
    Order order = 2;
}

message Order {
    string sessionCode = 1;
    string shortCode = 2;
    string id = 3;
    string customerId = 4;
    string merchantId = 5;
    string merchantName = 6;
    string merchantProfileImageId = 7;
    string merchantCategory = 8;
    string merchantOrderId = 9;
    string merchantOrderNumber = 10;
    string merchantStore = 11;
    string merchantCash = 12;
    string merchantCashierId = 13;
    string merchantCashier = 14;
    int64 saleDate = 15;
    double total = 16;
    double totalOriginal = 17;
    double cashback = 18;
    double discount = 19;
    double swipDiscount = 20;
    repeated Purchase purchases = 21;
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;
    PaymentMethod paymentMethod = 33;
    int32 apiVersion = 34;
    string otp = 35;
    string slip = 36;
    string rrn = 37;
    string authorizationCode = 38;
    string terminalNo = 39;
    string pan = 40;
    double merchantDiscount = 41;
    string discountCard = 42;
}

Получить все заказы

Запрашивает список заказов за указанный период. Необходим, если на кассе произошел сбой. Данный метод возвращает заказы только в статусе CLOSED.

Формат запроса

Для получения всех заказов необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения.
`from`	google.protobuf.UInt64Value, необязательный	Дата начала периода (в миллисекундах с 01.01.1970).
`to`	google.protobuf.UInt64Value, необязательный	Дата окончания периода (в миллисекундах с 01.01.1970).

Если период не будет указан, то сервер вернет список заказов за текущий день.

Пример сообщения запроса

message CashGetOrderListRequest {
    string requestId = 1;
    google.protobuf.UInt64Value from = 2;
    google.protobuf.UInt64Value to = 3;
}

Формат ответа

В ответ приходит список объектов заказа за текущий день или указанный период.

Пример сообщения ответа

message CashGetOrderListResponse {
    string requestId = 1;
    repeated Order orders = 2;			// список объектов заказа
}

message Order {
    string sessionCode = 1;
    string shortCode = 2;
    string id = 3;
    string customerId = 4;
    string merchantId = 5;
    string merchantName = 6;
    string merchantProfileImageId = 7;
    string merchantCategory = 8;
    string merchantOrderId = 9;
    string merchantOrderNumber = 10;
    string merchantStore = 11;
    string merchantCash = 12;
    string merchantCashierId = 13;
    string merchantCashier = 14;
    int64 saleDate = 15;
    double total = 16;
    double totalOriginal = 17;
    double cashback = 18;
    double discount = 19;
    double swipDiscount = 20;
    repeated Purchase purchases = 21;
    double paid = 22;
    double unconfirmed = 23;
    double closeAmount = 24;
    int32 availablePoints = 25;
    string error = 26;
    double pointsRate = 27;
    double pointsAsDiscount = 28;
    int32 awardPoints = 29;
    int32 withdrawPoints = 30;
    PaymentWay paymentWay = 31;
    OrderStatus orderStatus = 32;
    PaymentMethod paymentMethod = 33;
    int32 apiVersion = 34;
    string otp = 35;
    string slip = 36;
    string rrn = 37;
    string authorizationCode = 38;
    string terminalNo = 39;
    string pan = 40;
    double merchantDiscount = 41;
    string discountCard = 42;
}

Сохранить настройки кассы

Используется для сохранения на сервере прикрепленного к кассе QR-кода.

Формат запроса

Для сохранения настроек кассы необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`settingName`	string, обязательный	Название настройки (QR).
`settingValue`	string, обязательный	Значение настройки.

Пример сообщения запроса

message CashSaveSettingRequest {
    string requestId = 1;
    string settingName = 2;
    string settingValue = 3;
}

Формат ответа

В ответ приходит идентификатор сообщения.

1
2
3

message CashSaveSettingResponse {
    string requestId = 1;
}

Получить настройки кассы

Запрашивает на сервере значение прикрепленного к кассе QR-кода.

Формат запроса

Для получения настроек кассы необходимо отправить сообщение с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`requestId`	string, обязательный	Уникальный идентификатор сообщения в сокет канале.
`settingName`	string, обязательный	Название настройки (QR).

Пример сообщения запроса

message CashGetSettingRequest {
    string requestId = 1;
    string settingName = 2;
}

Формат ответа

В ответ приходят настройки кассы.

Пример сообщения ответа

message CashGetSettingResponse {
    string requestId = 1;
    string settingName = 2;
    string settingValue = 3;
}

Сокет API кассы

Использование API

Идентификация заказа и сессии

Транспорт и протокол

Формат сообщений

Типы сообщений

Коды ошибок и их описание

Объект ошибки

Объект заказа

Аутентификация

Формат запроса

Формат ответа

Проверить соединение

Формат запроса

Формат ответа

Создать заказ

Формат запроса

Формат ответа

Получить заказ

Формат запроса

Формат ответа

Применить скидку мерчанта

Формат запроса

Формат ответа

Обновить статус заказа

Формат ответа

Закрыть заказ

Формат запроса

Формат ответа

Получить все заказы

Формат запроса

Формат ответа

Сохранить настройки кассы

Формат запроса

Формат ответа

Получить настройки кассы

Формат запроса

Формат ответа