Перейти к концу метаданных
Переход к началу метаданных
Что такое API Set10
API Set10 с точки зрения клиента и вендора
Общая информация
Программный комплекс Set Retail 10 представляет из себя платформу, которая имеет внешний API для разработчиков.
При помощи API возможно создание подключаемых плагинов, для расширения базового функционала. Плагины позволяют интегрироваться с различными внешними системами для осуществления: оплаты чека различными типами платежей, расчета скидок во внешних системах лояльности, добавления карт процессинговых систем и прочего взаимодействия.
API позволяет на высоком уровне абстракции взаимодействовать с кассовым ПО, его пользователем и подключенным кассовым оборудованием.
Принципы взаимодействия по API
API представляет из себя набор интерфейсов и классов на языке Java версии 8.
Взаимодействие Set Retail 10 с подключаемыми плагинами основано на принципах:
- инверсии управления (Inversion of Control, IoC);
- функций обратного вызова (Callback);
- событийно-ориентированного подхода (Event driven).
Создание плагина
Для создания плагина необходимо добавить в зависимости библиотеку с API, имплементировать требуемые интерфейсы и заполнить файл описания в формате XML.
Файл описания содержит в себе информацию о плагине: его тип, название и список необходимых параметров для настройки в эксплуатационной среде, с указанием их типа и описания. На основании этих данных Set Retail 10 позволяет зарегистрировать плагин в системе и настроить его работу соответствующим образом.
Написание плагина рекомендуется выполнять на языке Java, хотя возможно использование и других языков выполняющихся в виртуальной среде Java (JVM). Также, для удобства, допустимо использование различных публично распространяемых библиотек определенных версий: apache commons, guava, log4j и др.
Пример реализации плагина на языке Java
/**
* Пример реализации плагина оплаты.
* Данный класс демонстрирует концепцию взаимодействия с кассовым ПО Set Retail 10
*/
public class PaymentPluginExample implements POSPlugin, PaymentPlugin {
private Facade facade; // Через этот интерфейс будем взаимодействовать с модулями кассы Set Retail 10
public PaymentPluginExample() { // Класс должен иметь дефолтный конструктор
}
/**
* При запуске касса создаёт экземпляр класса и вызывает метод инициализации
*/
@Override
public void initialization(PluginRegistrator registrator, Facade facade) {
this.facade = facade;
// регистрируем этот класс как плагин оплат
registrator.registerPaymentPlugin(this);
}
/**
* Когда на кассе будет выбран этот плагин для оплаты чека, будет вызван этот метод.
* Аргумент PaymentRequest содержит:
* - сумму к оплате
* - информацию о текущем оплачиваемом чеке (позиции чека, карты, скидки, оплаты)
* - класс интерфейса PaymentCallback для возврата информации об оплате
*/
@Override
public void eventPaymentRequested(final PaymentRequest request) throws Exception {
// запрашиваем кассу показать экран сканирования с подпиской на события
facade.getForms().showScanForm("Просканируйте QR код электронного кошелька", new ScanFormListener() {
// пользователь нажал отмену
@Override
public void eventCancelPressed() {
// через callback сообщаем, что оплата не была выполнена
request.getPaymentCallback().paymentNotCompleted();
}
// на форме был просканирован штрихкод
@Override
public void eventBarcodeScanned(String barcode) {
// запускаем процесс оплаты
startPaymentProcess(request, barcode);
}
});
}
private void startPaymentProcess(final PaymentRequest request, String barcode) {
try {
// Т.к. процесс может занять долгое время, показываем форму со спинером
// У данной формы нет listener-а, значит пользователь не сможет прервать этот процесс
facade.getForms().showSpinnerForm("Идёт проверка кошелька");
// пытаемся выполнить процесс оплаты
doRemoteRequest(request, barcode);
} catch (Exception e) {
// в случае возникших ошибок показываем форму с сообщением об ошибке
facade.getForms().showErrorForm("Ошибка выполнения оплаты", new MessageFormListener() {
@Override
public void messageReaded() {
// после прочтения сообщения об ошибке
// через callback сообщаем, что оплата не была выполнена
request.getPaymentCallback().paymentNotCompleted();
}
});
}
}
private void doRemoteRequest(PaymentRequest request, final String barcode) throws Exception {
// читаем настройки плагина оплаты
String url = facade.getPluginSettings().getProperty("provider.url");
Integer timeout = Integer.valueOf(facade.getPluginSettings().getProperty("timeout"));
String login = facade.getPluginSettings().getProperty("user.login");
String password = facade.getPluginSettings().getProperty("user.password");
// выполнение запроса, получение ответа
// формируем данные оплаты для сохранения в БД Set Retail 10
PaymentData paymentData = new PaymentData();
paymentData.setSum(request.getSumToPay());
String transactionNumber = "45AB-DEF8-FF00-EE13";
String authorizationCode = "1234567890";
// данные о транзакции оплаты добавляем в виде key,value
paymentData.addField("autorization.code", authorizationCode);
paymentData.addField("transaction.number", transactionNumber);
paymentData.addField("someKey", "someData");
// если необходимо формируем слип, который будет распечатан вместе с чеком
PrintedSlip printedSlip = new PrintedSlip();
printedSlip.addTextBlock("С вашего кошелька успешно списано ");
printedSlip.addTextBlock(request.getSumToPay().toString() + " руб.");
printedSlip.addTextBlock("Номер транзакции:");
printedSlip.addTextBlock(transactionNumber);
paymentData.addPrintedSlip(printedSlip);
// через callback сообщаем, что оплата была успешно выполнена
request.getPaymentCallback().paymentCompleted(paymentData);
}
}