При получении данных заказа из информационной системы предприятия через веб-сервис или от собственного приложения предприятия в приложение Assist mPOS передаются необходимые входные данные.
Входные данные для приложения Assist mPOS
Параметр | Обяза-тельный | Описание | Комментарий | Пример в формате JSON |
ordernum | Нет | Уникальный номер заказа из внешней системы | На входе используется валидация. Regex для проверки "[^\\w\\(\\){}\\[\\]№\\s\"\'+!%*+,./:;=?@^_`|~-]" | "ordernum":"12354_5678" |
amount | Да | Сумма заказа | Если значение отличается от значения произведения переданных в строке items значений price и quantity | "amount":"1234.56" |
amount_prepaid | Нет | Сумма ранее полученной преоплаты | "amount_prepaid":"1000.00" | |
currency | Нет | Валюта заказа, ISO код | В настоящий момент возможна оплата заказов только в рублях. | "currency":"RUB" |
merchantid | Нет/Да | Идентификатор предприятия в АПК Ассист. Параметр обязателен, если его значение отсутствует в настройках приложения. | "merchant_id":"223344" | |
merchant_name | Нет | Для печати в чеке. Пример: ООО "Яркий фотомаркет" | "merchant_name":"ООО Мерчант" | |
comment | Нет | Комментарий к заказу | "comment":"скидка 8 марта" | |
clientname | Нет | Имя покупателя | "clientname":"Иван" | |
clientemail | Нет | Email адрес покупателя | "clientmail":"client@mail.ru" | |
clientphone | Нет | Номер мобильного телефона покупателя | "clientphone":"12345678" | |
payment_address | Нет | Место расчета для печати в чеке | "payment_address":"ул. Новая, д.23" | |
cashier | Нет | Фамилия кассира для печати в чеке | "cashier":"Иванов" | |
taxation_system | Нет/Да | Идентификатор системы налогообложения | Код в соответствии со справочником типов системы налогообложения | "taxation_system":"0" |
items | Нет | Товарные позиции в формате json : {"items":[ { "id": "Позиция в чеке", "product" : "Код номенклатуры", "type" : "Предмет расчета" "name" : "Наименование", "display_name" : "Опциональное название позиции, только для отображения в приложении" "price" : "Цена за единицу номенклатуры, без учета скидки", "quantity" : "Количество", "tax" : "Идентификатор ставки налога", "amount" : "Стоимость позиции итого" "discount_amount" : "Скидка по позиции итого" "payment_method" : "Способ расчета"}, ... ] } | Валидация данных:
| "items":[ {"id":"1", "product":"16537615", "type":1, "name":"Чехол FUJIFILM LC-X100F для X100F, коричневый", "display_name": "Компактный фотик" "price":"6500.00", "quantity":1, "tax":"vat0", "amount":"6500.00", "discount_amount":"490.00", "payment_method":"4"} ] |
allow_edit_item_quantity | Нет | Разрешено ли пользователю изменять количество позиций заказа | Допустимые значения false или true (по умолчанию false) | "allow_edit_item_quantity":true |
allow_remove_item | Нет | Разрешено ли пользователю удалять позиции заказа | Допустимые значения false или true (по умолчанию false) | "allow_remove_item":true |
Получение данных из информационной системы предприятия через веб-сервис
Для получения приложением Assist mPOS данных заказа через веб-сервис сначала необходимо настроить соответствующие параметры (URL информационной системы предприятия, наименование учетной записи пользователя и пароль для доступа к веб-сервису информационной системы предприятия) в Личном кабинете АПК Ассист. Настройка параметров описана в п.8.2.11 «Настройки mPOS» инструкции по работе с Личным кабинетом».
После ввода номера заказа пользователем приложение осуществляет запрос методом GET на указанный в настройках сервер предприятия с параметром ID заказа.
Примерный вид запроса:
GET https://<URL сервера информационной системы предприятия>?orderid=XXXX,
где XXXX – уникальный идентификатор заказа в системе предприятия (номер заказа).
В ответ информационная система предприятия должна передать данные заказа в формате JSON в соответствии с таблицей входных данных для приложения Assist mPOS, приведенной выше.
В случае ошибки информационная система предприятия должна ответить согласованным сообщением об ошибке, например, «Заказ не найден» или «Заказ уже оплачен».
При получении из информационной системы предприятия заказов списком приложение осуществляет запрос методом GET на указанный в настройках сервер предприятия с параметром ID пользователя.
Примерный вид запроса:
GET https://<URL сервера информационной системы предприятия>?id=XXXX,
где XXXX – уникальный идентификатор пользователя в системе предприятия (номер заказа).
Получение данных от собственного приложения предприятия
Собственное приложение предприятия, установленное на том же мобильном устройстве, инициирует оплату заказа, передавая приложению Assist mPOS данные заказа.
для приложения под ОС Android
Данные заказа в формате JSON передаются через Intent как строка (extra string):
Intent.putExtra(Intent.EXTRA_TEXT, json)
Тип данных: Intent.setType("application/json")
Intent action: "ru.assisttech.assistmpos.PAY"
Данные заказа передаются в соответствии с таблицей входных данных для приложения Assist mPOS, приведенной выше.
Результат оплаты возвращается собственному приложению предприятия приложением Assist mPOS также в формате JSON через Intent как строка (extra string):
Intent.putExtra(Intent.EXTRA_TEXT, json)
дополнительно устанавливается тип данных Intent.setType("application/json").
для приложения под ОС iOS
Приложение Assist mPOS вызывается через локальный URL «assistmpos://?» + base64_encoded_string -строка закодированных с помощью base64 данных.
Вызов: UIApplication.shared.open(url, options: [:], completionHandler: nil);
Формат данных: {"appname":"assistpmoslauncher","type":"payment", "data":""}, при этом:
- данные заказа в формате JSON (см. таблицу входных данных выше) передаются в поле «data»;
- url-scheme вызывающего приложения для передачи данных по заказу обратно передается в поле «appname»;
- тип оплаты («payment» - для оплаты и «cancel» - для отмены) передается в поле «type».
Результат оплаты возвращается собственному приложению предприятия приложением Assist mPOS также в формате JSON с помощью вызова собственного приложения предприятия через URL url: "appname://?" + base64_encoded_string, где "appname" - параметр, полученный при запросе оплаты, а base64_encoded_string - JSON с результатом обработки транзакции закодированный в base64.
В случае возникновения ошибки обратный вызов не осуществляется.
Выходные параметры (результат оплаты)
Параметр (JSON имя поля) | Обязательный | Описание |
ordernum | Да | Номер заказа |
orderstate | Да | Статус заказа |
billnumber | Нет | Внутренний номер Ассист |
amount | Да | Сумма заказа |
currency | Да | Валюта заказа, ISO код |
clientmail | Нет | Адрес электронной почты покупателя |
clientphone | Нет | Номер телефона покупателя |
payment_mode | Да | Способ оплаты (CASH/CARD) |
operationdate | Нет | Дата и время операции (GMT) |
cardtype | Нет | Тип платежной системы (VISA/MC) |
cardmask | Нет | Маскированный PAN |
cardholder | Нет | Держатель карты |
cardexpire | Нет | Срок действия карты |
fiscal_printer_serial* | Нет | Серийный номер ККТ |
fiscal_printer_shift* | Нет | Номер смены в ККТ |
fiscal_storage_number* | Нет | Номер фискального накопителя |
fiscal_doc_number* | Нет | Сквозной номер фискального документа |
fiscal_doc_mark* | Нет | Фискальный признак |
fiscal_storage_number_per_shift* | Нет | Номер фискального документа в смене |
fiscal_doc_datetime* | Нет | Дата формирования фискального документа |