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