1 Термины и определения
2 Общее описание
3 Рекомендуемая схема использования
4 Список удаленных процедур
- 4.1 init
  - 4.1.1 MerchantCredentials
  - 4.1.2 MerchantCredentialsStatus
- 4.2 createOrder
  - 4.2.1 NewOrderData
  - 4.2.2 OrderStatusUpdate
- 4.3 getFrameStream
  - 4.3.1 Frame
- 4.4 identify
  - 4.4.1 Pincode
  - 4.4.2 Customer
- 4.5 calculateLoyalty
  - 4.5.1 Loyalty
  - 4.5.2 OrderStatusUpdate
- 4.6 pay
  - 4.6.1 PayOrder
  - 4.6.2 PaymentStatusUpdate
- 4.7 closeOrder
  - 4.7.1 OrderAmount
  - 4.7.2 OrderStatusUpdate
- 4.8 refund
  - 4.8.1 OrderAmount
  - 4.8.2 RefundStatusUpdate

Термины и определения

Клиент SWiP SDK (клиент) - программа с графическим интерфейсом, которая устанавливается на кассе самообслуживания.

Сервер SWiP SDK (сервер) - консольное приложение, представляющее собой gRPC сервис, который работает по протоколу SWiP SDK.

STP Gateway - сервер для оплаты по лицу, входящий в SWiP Cloud.

Cash Gateway - сервер для работы с кассой, входящий в SWiP Cloud.

SWIP Cloud - набор связанных сервисов SWiP.

Касса самообслуживания (КСО) - устройство, позволяющее автоматизировать процесс самообслуживания оплаты товара.

Общее описание

SWiP SDK представляет собой описание множества удаленных процедур, сообщений и перечислений gRPC сервиса.

Список удаленных процедур

Ниже перечислены gRPC процедуры, используемые в SWiPService:

service SWiPService {
    rpc init (MerchantCredentials) returns (MerchantCredentialsStatus);
    rpc createOrder (NewOrderData) returns (OrderStatusUpdate);
    rpc getFrameStream (google.protobuf.Empty) returns (stream Frame);
    rpc identify(Pincode) returns (Customer);
    rpc calculateLoyalty(Loyalty) returns (OrderStatusUpdate);
    rpc pay(PayOrder) returns (PaymentStatusUpdate);
    rpc closeOrder (OrderAmount) returns (OrderStatusUpdate);
    rpc refund (OrderAmount) returns (RefundStatusUpdate);
}

init

Инициализация настроек мерчанта выполняется путем вызова процедуры init() с настройками в сообщении MerchantCredentials. Процедура init() должна быть проведена перед использованием остальных процедур сервера SWiP SDK. Настройки мерчанта хранятся в оперативной памяти, поэтому вызов процедуры init() требуется выполнять при перезагрузке сервера.

rpc init (MerchantCredentials) returns (MerchantCredentialsStatus);

MerchantCredentials

Для передачи настроек от клиента к серверам SWiP (Cash Gateway и STP Gateway) используется сообщение MerchantCredentials:

message MerchantCredentials {
    string merchantId = 1; 
    string storeId = 2; 
    string cashId = 3; 
    string token = 4; 
    }

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

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

MerchantCredentialsStatus

Результат работы от сервера к клиенту возвращается в виде сообщения MerchantCredentialsStatus:

message MerchantCredentialsStatus {
    MerchantCredentialsCode code = 1;   // код результата проверки полномочий мерчанта
    string errorMessage = 2;            // детали ошибки, в случае ее возникновения
}

Перечисление MerchantCredentialsCode имеет вид:

enum MerchantCredentialsCode {
    MERCHANT_CREDENTIALS_EMPTY = 0; 
    MERCHANT_CREDENTIALS_OK = 1; 
    MERCHANT_CREDENTIALS_FAILED = 2;  
}

Описание значений перечисления MerchantCredentialsCode:

Значение	Описание

Значение	Описание
`MERCHANT_CREDENTIALS_EMPTY`	Настройки не были переданы.
`MERCHANT_CREDENTIALS_OK`	Настройки переданы успешно.
`MERCHANT_CREDENTIALS_FAILED`	Попытка соединения с серверами SWiP не состоялась, детали в поле `errorMessage`

createOrder

Создание заказа выполняется путем вызова процедуры createOrder.

rpc createOrder (NewOrderData) returns (OrderStatusUpdate);

NewOrderData

Для создания заказа используется сообщение NewOrderData, которое содержит данные для формирования заказа со списком покупок.

message NewOrderData {
    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;
}

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; 
    }

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

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

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

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

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит успешно созданный заказ. Далее идентификатор этого заказа используется для его оплаты и закрытия.

message OrderStatusUpdate {
    OrderStatusUpdateCode code = 1;     // код, характеризующий результат операции
    Order order = 2;                    // объект заказа
    string errorMessage = 3;            // детали ошибки
}

message Order {
    string sessionCode = 1;                   // код сессии, генерируемый кассой, в виде UUID
    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;                     // дата продажи (в миллисекундах с 01.01.1970)
    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;                   // доля рубля в 1 балле
    double pointsAsDiscount = 28;             // скидка, полученная при списании баллов
    int32 awardPoints = 29;                   // начисленные баллы
    int32 withdrawPoints = 30;                // списанные баллы
    PaymentWay paymentWay = 31;               // способ оплаты (APP, STP)
    OrderStatus orderStatus = 32;             // статус заказа (OPEN, CLOSED, LOYALTY_CALCULATION)
    PaymentMethod paymentMethod = 33;         // метод оплаты (CARD, CREDIT, CASH)
    int32 apiVersion = 34;                    // версия API
    string otp = 35;                          // дополнительный идентификатор заказа (one time paid)
    string slip = 36;                         // форматированный текст (80 символов в ширину) с банковской информацией о платеже
    string rrn = 37;                          // уникальный идентификатор банковской транзакции
    string authorizationCode = 38;            // авторизационный код платежа
    string terminalNo = 39;                   // номер банковского терминала
    string pan = 40;                          // маскированный номер карты
    double merchantDiscount = 41;             // скидка, предоставляемая мерчантом
    string discountCard = 42;                 // идентификатор дисконтной карты
}

Перечисление OrderStatusUpdateCode имеет вид:

enum OrderStatusUpdateCode {
    ORDER_STATUS_UPDATE_EMPTY = 0;      // значение не присвоено
    ORDER_STATUS_UPDATE_OK = 1;         // процедура выполнилась успешно
    ORDER_STATUS_UPDATE_FAILED = 2;     // произошел сбой, детали ошибки в поле errorMessage
}

Описание значений перечисления OrderStatusUpdateCode:

Значение	Описание

Значение	Описание
`ORDER_STATUS_UPDATE_EMPTY`	Значение не присвоено.
`ORDER_STATUS_UPDATE_OK`	Процедура выполнена успешно.
`ORDER_STATUS_UPDATE_FAILED`	Произошел сбой, детали ошибки в поле `errorMessage`.

Перечисление PaymentWay имеет вид:

enum PaymentWay {
    PAYMENT_WAY_EMPTY = 0;
    PAYMENT_WAY_APP = 1;
    PAYMENT_WAY_STP = 2;
}

Описание значений перечисления PaymentWay:

Значение	Описание

Значение	Описание
`PAYMENT_WAY_EMPTY`	Значение не присвоено.
`PAYMENT_WAY_APP`	Оплата через мобильное приложение.
`PAYMENT_WAY_STP`	Оплата через Selfie2Pay.

Перечисление OrderStatus имеет вид:

enum OrderStatus {
    ORDER_STATUS_EMPTY = 0;
    ORDER_STATUS_OPEN = 1;
    ORDER_STATUS_CLOSED = 2;
    ORDER_STATUS_LOYALTY_CALCULATION = 3;
}

Описание значений перечисления OrderStatus:

Значение	Описание

Значение	Описание
`ORDER_STATUS_EMPTY`	Значение не присвоено.
`ORDER_STATUS_OPEN`	Заказ открыт.
`ORDER_STATUS_CLOSED`	Заказ закрыт.
`ORDER_STATUS_LOYALTY_CALCULATION`	По заказу проведен расчет внешней лояльности.

Перечисление PaymentMethod имеет вид:

enum PaymentMethod {
    PAYMENT_METHOD_EMPTY = 0;
    PAYMENT_METHOD_CARD = 1;
    PAYMENT_METHOD_CREDIT = 2;
    PAYMENT_METHOD_CASH = 3;
}

Описание значений перечисления PaymentMethod:

Значение	Описание

Значение	Описание
`PAYMENT_METHOD_EMPTY`	Значение не присвоено.
`PAYMENT_METHOD_CARD`	Оплата картой.
`PAYMENT_METHOD_CASH`	Оплата наличными.

getFrameStream

Включение камеры, выполнение и сохранение наилучшего снимка совершается путем вызова удаленной потоковой процедуры getFrameStream:

rpc getFrameStream (google.protobuf.Empty) returns (stream Frame);

Frame

Клиент принимает от сервера поток кадров в виде сообщения Frame:

message Frame {
    bytes frame = 1;                      // кадры видеопотока с RGB камеры с дорисованной декоративной рамкой
    DetectionStatus detectionStatus = 2;  // статус процесса распознавания
    string errorMessage = 3;              // детали ошибки, в случае ее возникновения
}

Перечисление DetectionStatus для передачи статуса процесса распознавания имеет вид:

enum DetectionStatus {
    DETECTION_EMPTY = 0; 
    BESTSHOT_FOUND = 1; 
    DETECTION_FAILED = 2; 
    DETECTION_TIMEOUT = 3;
    NO_FACE_DETECTED = 4;
    TOO_MANY_FACES = 5;
    FACE_IS_NOT_VALID = 6;
    INCORRECT_HEAD_POSE = 7;
    LIVENESS_FAILED = 8;
    FACE_OUTSIDE_BORDERS = 9;
    SMALL_FACE_SIZE = 10;
    TOO_BLURRY = 11;
    HIGH_LEVEL_LIGHTNESS = 12;
    LOW_LEVEL_LIGHTNESS = 13;
    LOW_QUALITY = 14;
    INCORRECT_DEPTH_FRAME = 15;
}

Описание значений перечисления DetectionStatus:

Значение	Описание

Значение	Описание
`DETECTION_EMPTY`	Статус не передан.
`BESTSHOT_FOUND`	Найден лучший кадр, который подходит для распознавания.
`DETECTION_FAILED`	Невозможно выполнить распознавание.
`DETECTION_TIMEOUT`	Время ожидания истекло до завершения процесса поиска лица.
`NO_FACE_DETECTED`	Нет лица в кадре.
`TOO_MANY_FACES`	Много лиц в кадре.
`FACE_IS_NOT_VALID`	Вероятность обнаружения лица в кадре слишком мала.
`INCORRECT_HEAD_POSE`	Некорректная поза головы.
`LIVENESS_FAILED`	Проверка на живучесть не пройдена.
`FACE_OUTSIDE_BORDERS`	Лицо вне области распознавания.
`SMALL_FACE_SIZE`	Слишком маленькое лицо.
`TOO_BLURRY`	Изображение слишком размытое для проведения распознавания.
`HIGH_LEVEL_LIGHTNESS`	Изображение слишком засвеченное для проведения распознавания.
`LOW_LEVEL_LIGHTNESS`	Изображение слишком затемненное для проведения распознавания.
`LOW_QUALITY`	Монохромное изображение (в темноте) не подходит для проведения распознавания.
`INCORRECT_DEPTH_FRAME`	Некорректной снимок глубины. Если ошибка повторяется, проверьте камеру глубины, возможно, она вышла из строя.

identify

Идентификация покупателя выполняется путем вызова процедуры identify:

rpc identify(Pincode) returns (Customer);

Pincode

Для получения идентификатора покупателя сообщение Pincode передается с пустым значением.

1
2
3

message Pincode {
    string pincode = 1;
}

Customer

В ответ приходит сообщение Customer, которое содержит в себе идентификатор покупателя, код возврата.

Идентификатор пользователя SWiP (customerId) является временным. По умолчанию время действия этого идентификатора - 10 минут. После истечения таймаута идентификатор становится недействительным.

message Customer {
    string id = 1;                            // временный идентификатор пользователя SWiP
    bool adult = 2;                           // является ли покупатель совершеннолетним
    string extId = 3;                         // внешний идентификатор мерчанта
    IdentificationCode code = 4;              // код возврата
    string errorMessage = 5;                  // сообщение об ошибке
}

Перечисление IdentificationCode для передачи кода возврата имеет вид:

enum IdentificationCode {
    IDENT_EMPTY = 0; 
    IDENT_OK = 1;
    IDENT_PIN_REQUIRED = 2; 
    IDENT_CUSTOMER_NOT_RECOGNIZED = 3; 
    IDENT_CUSTOMER_NOT_FOUND = 4;
    IDENT_CUSTOMER_NOT_VALID = 5; 
    IDENT_INCORRECT_PIN = 6; 
    IDENT_PIN_ATTEMPT_EXCEEDED = 7; 
    IDENT_FAILED = 8; 
}

Описание значений перечисления IdentificationCode:

Значение	Описание

Значение	Описание
`IDENT_EMPTY`	Значение не присвоено.
`IDENT_OK`	Пользователь идентифицирован.
`IDENT_PIN_REQUIRED`	Необходимо ввести ПИН-код.
`IDENT_CUSTOMER_NOT_RECOGNIZED`	Пользователь не распознан.
`IDENT_CUSTOMER_NOT_FOUND`	Пользователь не зарегистрирован в системе SWiP.
`IDENT_CUSTOMER_NOT_VALID`	Пользователь не прошел валидацию (ждет проверки).
`IDENT_INCORRECT_PIN`	Неверный ПИН-код.
`IDENT_PIN_ATTEMPT_EXCEEDED`	Количество попыток ввода пин-кода исчерпано.
`IDENT_FAILED`	Ошибка идентификации.

Если в сообщении Customer пришел код IDENT_PIN_REQUIRED, то необходимо повторно выполнить процедуру identify, а в сообщении Pincode передать значение ПИН-кода.

calculateLoyalty

Только для клиентов, использующих программу лояльности SWiP.

Введение баллов запускается процедурой calculateLoyalty:

rpc calculateLoyalty(Loyalty) returns (OrderStatusUpdate);

Loyalty

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

message Loyalty {
    string orderId = 1;
    string customerId = 2;
    uint32 pointsToWithdraw = 3;
}

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

Параметр	Тип	Описание
`orderId`	string, обязательный	Идентификатор заказа в системе SWiP.
`customerId`	string, обязательный	Идентификатор клиента в системе SWiP.
`points`	int32, обязательный	Баллы, которые ввел пользователь.

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит обновленный заказ. Сообщение OrderStatusUpdate описано в процедуре создания заказа.

pay

Оплата заказа совершается путем вызова процедуры pay:

rpc pay(PayOrder) returns (PaymentStatusUpdate);

PayOrder

Если процедура оплаты не была запущена в течение 10 секунд после успешной идентификации, то потребуется ввести ПИН-код при оплате заказа.

Для оплаты заказа используется сообщение PayOrder:

message PayOrder {
    string orderId = 1; 
    string customerId = 2; 
    double amountToPay = 3; 
    string pincode = 4; 
}

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

Параметр	Тип	Описание
`orderId`	string, обязательный	Идентификатор заказа в системе SWiP.
`customerId`	string, обязательный	Идентификатор клиента в системе SWiP.
`amountToPay`	string, обязательный	Сумма, которую касса передает для оплаты.
`pincode`	string, необязательный	ПИН-код, который необходимо ввести, если процедура оплаты не была запущена в течение 10 секунд.

PaymentStatusUpdate

В ответ приходит сообщение PaymentStatusUpdate, которое содержит успешно оплаченный заказ.

message PaymentStatusUpdate {
    PaymentStatusUpdateCode code = 1;   // код, характеризующий результат операции
    Order order = 2;                    // объект заказа
    string errorMessage = 3;            // детали ошибки
}

Перечисление PaymentStatusUpdateCode имеет вид:

enum PaymentStatusUpdateCode {
    PAYMENT_EMPTY = 0; 
    PAYMENT_OK = 1; 
    PAYMENT_PIN_REQUIRED = 2; 
    PAYMENT_INCORRECT_PIN = 3; 
    PAYMENT_PIN_ATTEMPT_EXCEEDED = 4; 
    PAYMENT_ID_EXPIRED = 5; 
    PAYMENT_FAILED = 6; 
}

Описание значений перечисления PaymentStatusUpdateCode:

Значение	Описание

Значение	Описание
`PAYMENT_EMPTY`	Значение не присвоено.
`PAYMENT_OK`	Оплата прошла успешно.
`PAYMENT_PIN_REQUIRED`	Необходимо ввести ПИН-код.
`PAYMENT_INCORRECT_PIN`	Введен неверный ПИН-код.
`PAYMENT_PIN_ATTEMPT_EXCEEDED`	Количество попыток ввода ПИН-кода исчерпано.
`PAYMENT_ID_EXPIRED`	Срок действия идентификатора пользователя истек (10 минут).
`PAYMENT_FAILED`	Произошла ошибка.

closeOrder

Закрытие заказа выполняется путем вызова процедуры closeOrder.

rpc closeOrder (OrderAmount) returns (OrderStatusUpdate);

OrderAmount

Для закрытия заказа используется сообщение OrderAmount, которое содержит идентификатор закрываемого заказа и сумму для закрытия.

Для отмены заказа в сумме для закрытия передается значение 0.

message OrderAmount {
    string orderId = 1; 
    double amount = 2; 
}

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

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

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит успешно закрытый заказ. Сообщение OrderStatusUpdate описано в процедуре создания заказа.

refund

Возврат заказа выполняется путем вызова процедуры closeOrder.

rpc refund (OrderAmount) returns (RefundStatusUpdate);

OrderAmount

Для возврата заказа используется сообщение OrderAmount, которое содержит идентификатор возвращаемого заказа и сумму возврата.

message OrderAmount {
    string orderId = 1; 
    double amount = 2; 
}

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

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

RefundStatusUpdate

В ответ приходит сообщение RefundStatusUpdate, которое содержит статус возвращенного заказа и платежный идентификатор.

message RefundStatusUpdate {
    RefundStatus status = 1;                // статус возврата
    string errorMessage = 2;                // детали ошибки
    string slip = 3;                        // платежный идентификатор (слип)
}

Перечисление RefundStatus для передачи статуса возврата имеет вид:

enum RefundStatus {
    REFUND_EMPTY = 0; 
    REFUND_SUCCESS = 1;
    REFUND_FAILED = 2;
}

Описание значений перечисления RefundStatus:

Значение	Описание

Значение	Описание
`REFUND_EMPTY`	Значение не присвоено.
`REFUND_SUCCESS`	Возврат выполнен успешно.
`REFUND_FAILED`	Произошла ошибка.

SWiP SDK

Термины и определения

Общее описание

Рекомендуемая схема использования

Список удаленных процедур

init

MerchantCredentials

MerchantCredentialsStatus

createOrder

NewOrderData

OrderStatusUpdate

getFrameStream

Frame

identify

Pincode

Customer

calculateLoyalty

Loyalty

OrderStatusUpdate

pay

PayOrder

PaymentStatusUpdate

closeOrder

OrderAmount

OrderStatusUpdate

refund

OrderAmount

RefundStatusUpdate