Фискальный регистратор
Модуль periphery-models подключаемый через build.gradle содержит набор классов (моделей) параметров и результатов операций фискализации чеков.
Для каждого действия (action) используется своя входящая модель (параметры фискального чека) и исходящая модель (результат фискализации). Смотрите таблицу соответствия операций и моделей.
Модели передаются и получаются в/из значения поля data в виде json строки, которая является сериализованным представлением модели.
Чтобы сериализовать модель в json строку, необходимо использовать метод toJSON().
Для десериализации json строки в соответствующую модель следует использовать следующий метод (нужно указать необходимый класс модели):
kotlin
GSONConverter.fromJSON(data, FDReceipt::class.java)
java
GSONConverter.fromJSON(data, FDReceipt.class);
Таблица соответствия операций и моделей:
| Название операции | Действие (action) |
Входящая модель | Исходящая модель |
|---|---|---|---|
| Фискализация чека | ru.lifepay.checkout.fiscal_registrar.register_receipt | FCRegisterReceiptParams | FDReceipt |
| Фискализация чека коррекции | ru.lifepay.checkout.fiscal_registrar.register_receipt_of_correction | FCRegisterReceiptOfCorrectionParams | FDReceiptOfCorrection |
Параметры входящего запроса
Фискализация чека
Действие: ru.lifepay.checkout.fiscal_registrar.register_receipt
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| data | String | да | Экземпляр класса FCRegisterReceiptParams сериализованный в json. |
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. Для облачной кассы Lifepay поддерживается механизм защиты от дублирования на основе request_id, смотрите раздел Защита от дублирования. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Смотрите раздел Передача дополнительных данных. |
| Boolean | нет | true/false - необходимо ли печатать чек на фискальном регистраторе. По умолчанию - true. В случае false, необходимо заполнять поле customerContacts модели FCRegisterReceiptParams (поле data). |
Фискализация чека коррекции
Действие: ru.lifepay.checkout.fiscal_registrar.register_receipt_of_correction
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| data | String | да | Экземпляр класса FCRegisterReceiptOfCorrectionParams сериализованный в json. |
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. Для облачной кассы Lifepay поддерживается механизм защиты от дублирования на основе request_id, смотрите раздел Защита от дублирования. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Смотрите раздел Передача дополнительных данных. |
Дополнительные параметры запроса
В зависимости от действия (action) и используемого типа фискального регистратора (ФР) в запросе могут быть дополнительные поля.
Тип используемого ФР выбирается вручную из приложения LIFE POS Checkout.
В текущей версии приложения доступен только один тип ФР - облачная касса Lifepay. Он же установлен по умолчанию, выбирать вручную его не нужно. Для использования облачной кассы Lifepay необходимо передавать дополнительные поля.
Дополнительные параметры запроса для облачной кассы Lifepay:
| Название | Тип | Обязательность | Описание |
|---|---|---|---|
| apikey | String | да | АПИ-ключ компании в системе Lifepay. Узнать свой АПИ-ключ можно в личном кабинете Lifepay. |
| target_serial | String | нет | Серийный номер принтера, на котором необходимо фискализировать данные. Если не задан, чек будет фискализирован на одном из подключенных (активных) фискальном регистраторе выбранным случайным образом. |
Также облачная касса Lifepay поддерживает механизм защиты от дублирования. Смотрите раздел Защита от дублирования.
Параметры результата запроса
В случае успешной обработки запроса приложение LIFE POS Checkout возвращает resultCode = Activity.RESULT_OK (-1) и экземпляр класса Intent с действием action которое было указано во входящем интенте.
Если resultCode отличается от Activity.RESULT_OK или если intent == null, то следует рассматривать данную ситуацию как ошибку.
Для фискальных регистраторов с поддержкой защиты от дублирования (например облачная касса Lifepay) данную ошибку стоит расценивать, как ошибку с со значением unknown_result_error в параметре error_type.
(Смотрите параметры результата запроса в случае ошибки и раздел Защита от дублирования.)
Успешная обработка запроса еще не означает успешной фискализации документа.
Для определения факта успешной/неуспешной фискализации следует ориентироваться на значение параметра code, значение 0 соответствует успешной фискализации, значение отличное от 0 соответствует ошибке.
Параметры результата запроса в случае успешной фискализации:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| code | Int | да | 0 - успешная фискализация документа. |
| request_id | String | да | Значение request_id, которое было передано в запросе. Если значение не было передано в запросе, то оно генерируется автоматически. |
| metadata | HashMap<String, String> | нет | Значение metadata, которое было передано в запросе. Извлекается через extras.getSerializable(“metadata”). |
| data | String | да | Сериализованные в json строку данные фискализации. |
Значения полей можно извлекать из экземпляра класса Bundle получаемого из свойства extras (метод getExtras() в случае java) класса Intent при помощи методов extras.getInt(...) и extras.getString(...).
Параметры результата запроса в случае ошибки:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| code | Int | да | Отличное от нуля значение. Означает, что произошла ошибка. |
| request_id | String | да | Значение request_id, которое было передано в запросе. Если значение не было передано в запросе, то оно генерируется автоматически. |
| metadata | HashMap<String, String> | нет | Значение metadata, которое было передано в запросе. Извлекается через extras.getSerializable(“metadata”). |
| error_type | String | да | Тип ошибки. Каждый тип имеет свою собственную логику обработки. Смотрите Типы ошибок. |
| message | String | да | Текст ошибки для вывода пользователю. |
| log | String | нет | Дополнительная информация об ошибке для разработчиков. Для пользователей ее выводить не нужно. Может быть полезной на этапе интеграции и тестирования. Может иметь большой размер. |
Тип ошибки (error_type) |
Описание |
|---|---|
| default_error | Обычная ошибка. |
| unknown_result_error | Результат запроса неизвестен. Выдается только для фискальных регистраторов и операций с поддержкой защиты от дублирования. Логику обработки смотрите в разделе Защита от дублирования. |
Защита от дублирования
Данный раздел актуален только для фискальных регистраторов и операций с поддержкой защиты от дублирования. ФР облачная касса Lifepay поддерживает механизм защиты от дублирования.
Для каждого запроса в приложение LIFE POS Checkout можно передавать параметр request_id.
В случае если его не передать, то его значение будет сгенерировано автоматически и вернется в успешном/неуспешном ответе.
Параметр request_id является уникальным идентификатором запроса и используется локально в приложении LIFE POS Checkout для работы механизма защиты от дублирования, в случае если фискальный регистратор и вызываемая операция поддерживает этот механизм.
Логика работы следующая:
У стороннего приложения имеются данные кассового чека, которые необходимо зафискализировать. Стороннее приложение локально генерирует request_id и отсылает запрос на фискализацию в LIFE POS Checkout вместе с этим request_id.
Если в результате выполнения запроса происходит успешная фискализация (
code == 0), то повторный запрос в LIFE POS Checkout с тем жеrequest_idбудет выдавать успешный результат с теми же данными, без выполнения фискализации. При этом нужно понимать, что этот механизм будет работать только локально на этом android устройстве. Если отправить запрос с тем жеrequest_idс другого android устройства, то такой чек будет зафискализирован. Данный механизм нужен, чтобы защититься от дублей локально, в определенное ограниченное время. К примеру для облачной кассы Lifepay запоминается локально 1000 последних запросов.Если в результате выполнения запроса происходит ошибка с
error_type == unknown_result_error, то это означает что результат запроса неизвестен, он может быть как успешным, так и нет. В этом случае при следующей попытке фискализации этого чека необходимо отсылать запрос с тем жеrequest_id, что и первоначальный. Это необходимо делать либо до получения успешного результата, либо до получения ошибки с другимerror_type.Если в результате выполнения запроса происходит ошибка с
error_type != unknown_result_error, то для следующей попытки фискализации этого чека необходимо сгенерировать новыйrequest_id. Т.к. запрос со старымrequest_idс большой долей вероятности в этом случае вернет ошибку.
Не используйте в качестве request_id какие либо внутренние глобальные идентификаторы заказа/продажи/чека из своей системы.
Как описано выше, для одного и того же чека может потребоваться изменять request_id в процессе попыток его фискализации.
Если вам требуется передавать ваш внутренний глобальный идентификатор заказа/продажи/чека вместе с чеком смотрите раздел Передача дополнительных данных.
Передача дополнительных данных
Приложение LIFE POS Checkout позволяет передавать дополнительные данные в запросах фискализации. Например это может быть уникальный идентификатор заказа/продажи/чека из вашей системы.
При использовании облачной кассы Lifepay это дает возможность находить чеки в личном кабинете Lifepay по переданным данным. Также эти данные можно получать в уведомлении об обработке документа, если в ЛК Lifepay указан URL для уведомлений.
Для реализации этого механизма в запросе фискализации необходимо передавать параметр metadata.
Пример заполнения параметра metadata:
kotlin
val metadata = HashMap<String, String>().apply {
put("OrderId", "12345")
}
intent.putExtra("metadata", metadata)
java
HashMap<String, String> metadata = new HashMap<>();
metadata.put("OrderId", "12345");
intent.putExtra("metadata", metadata);
Никаких проверок на дублирование для данного параметра не производится.