Удаленная фискализация
LifePay позволяет удаленно фискализировать продажи без необходимости во взаимодействии с принтером на месте продажи, либо агрегировать продажи из нескольких источников для печати на одном принтере
Пример распечатанного чека по запросу:
Отправка чека на фискализацию
Тип запроса:
POST
Формат данных:
Данные в теле запроса предварительно сериализуются в json-формат
Адрес URL:
https://alpha-sapi.yc.life-pay.ru/cloud-print/create-receipt
Условные обозначения в формате данных
| Обозначение | Описание |
|---|---|
| Ц | Атрибут, обозначающий, что данные реквизита должны быть представлены в виде цифры |
| С | Атрибут, обозначающий, что данные реквизита должны быть представлены в виде символа |
| {} | Атрибут повторяемый |
Описание полей
| Параметр | Тег | Тип | Описание | Обязательный | Формат | Максимальная длина |
|---|---|---|---|---|---|---|
| apikey | Строка | АПИ-ключ компании в системе Lifepay. Узнать свой АПИ-ключ можно в личном кабинете Lifepay. | Да | {С} | 255 | |
| login | Строка | Логин администратора компании или торговой точки в системе Lifepay. Если логин относится к торговой точке, к которой привязан принтер, документ будет отправлен на этот принтер. | Да | 7{Ц} | 11 | |
| purchase | Массив | Позиции в чеке. | Да | |||
| test | Целое | Тестовый режим отправки запроса без фискализации. Может принимать значения 0, 1, или отсутствовать (фискализировать по умолчанию). В тестовом режиме uuid сгенерирован не будет, оповещения о результате фискализации отправляться не будут. |
Нет | |||
| mode | Строка | Режим печати/отправки чека. Возможные значения:email - отправить электронный чек по email и/или смс,print_email - распечатать чек и отправить по email и/или смс. |
Нет | |||
| type | 1054 | Строка | Тип документа. Возможные значения:payment - приход (по умолчанию),refund - возврат прихода,buy - расход,buy_refund - возврат расхода. |
Нет | ||
| customer_phone | 1008 | Строка | Номер телефона клиента для отправки чека. | Нет | +{Ц} | 15 |
| customer_email | 1008 | Строка | Электронный адрес клиента для отправки чека. | Нет | {С}@{С} | 64 |
| customer_name | 1227 | Строка | Покупатель (клиент). | Нет | {С} | 256 |
| customer_inn | 1228 | Строка | ИНН покупателя. | Нет | {Ц} | 12 |
| card_amount | 1081 | Вещественное | Сумма, оплаченная клиентом по карте. Особое значение - #. |
Нет | {Ц}.ЦЦ | {Ц} | |
| cash_amount | 1031 | Вещественное | Сумма, оплаченная клиентом наличными. Особое значение - #. |
Нет | {Ц}.ЦЦ | {Ц} | |
| prepayment_amount | 1215 | Вещественное | Сумма, внесенная авансом. Особое значение - #. |
Нет | {Ц}.ЦЦ | {Ц} | |
| credit_amount | 1216 | Вещественное | Сумма, внесенная кредитными средствами. Особое значение - #. |
Нет | {Ц}.ЦЦ | {Ц} | |
| other_amount | 1217 | Вещественное | Сумма иной формы оплаты (встречное предоставление). Особое значение - #. |
Нет | {Ц}.ЦЦ | {Ц} | |
| cashier_name | 1021 | Строка | Имя кассира. | Нет | {С} | 64 |
| cashier_inn | 1203 | Строка | ИНН кассира. | Нет | {Ц} | 12 |
| target_serial | Строка | Серийный номер принтера, на котором необходимо фискализировать данные. Если не задан, чек будет фискализирован на одном из подключенных (активных) фискальных принтеров. | Нет | {С} | ||
| target_kkt_group_uuid | Строка | Идентификатор группы касс для фискализации. При задании параметра чек будет фискализирован на одном из ККТ, входящих в указанную группу. Объединить кассы в группы, и получить идентификатор можно в Личном кабинете Lifepay. | Нет | {С} | ||
| chpu_login | Строка | Логин, на который необходимо направить чек после печати фискального. | Нет | 7{Ц} | ||
| ext_id | Строка | Идентификатор в сторонней системе. В случае, если в систему повторно передан запрос с одинаковым ext_id, документ создан не будет, сервер вернет uuid первого документа. | Нет | {С} | 50 | |
| order_number | Строка | Номер заказа в сторонней системе. Может использоваться для поиска чека в личном кабинете. | Нет | {С} | ||
| callback_url | Строка | URL для отправки уведомления об обработке документа. Уведомление будет сформировано при смене статуса обработки документа на “обработан”, “ожидает повтора”, “ошибка”. | Нет | {С} | 255 | |
| callback_data | Строка | Структура | Массив | Пользовательские данные, которые будут отправлены обратно на URL, указанный в параметре callback_url. | Нет | |||
| ref_uuid замечание |
Строка | Идентификатор, который вернул сервер при создании документа. Может использоваться только при возврате прихода (см. замечания). | Нет | {С} | 50 | |
| pos описание пример |
Структура | Опции для подключенного POS-терминала (см. описание поля и замечания). | Нет | |||
| agent описание замечание пример |
1057 | Структура | Целое | Признак агента. | Нет | ||
| tax_system замечание |
1055 | Строка | Система налогообложения. Возможные значения: osn - ОСНusn6 - УСН доходusn15 - УСН доход-расходeshn - ЕСНpatent - Патент |
Нет | ||
| payment_place | 1187 | Строка | Место осуществления расчетов между пользователем и покупателем (клиентом) | Нет | {С} | 256 |
| additional_receipt_details | 1192 | Строка | Дополнительный реквизит чека (БСО) | Нет | {С} | 16 |
| receipt_header_lines описание пример |
Массив | Кастомные строки заголовка чека. | Нет | |||
| sender_email | 1117 | Строка | Электронный адрес (email) отправителя чеков. | Нет | {С}@{С} | 64 |
| additional_user_detail описание |
1084 | Структура | Дополнительный реквизит пользователя. | Нет | ||
| internet_payment | 1125 | Булево | Признак применения ККТ при осуществлении расчета в безналичном порядке в сети «Интернет» | Нет | B |
Пример содержимого поля purchase:
{
"products": [
{
"name": "Ананас",
"price": 110,
"quantity": 1,
"tax": "vat22",
"unit": "piece",
"discount": {
"type": "percent",
"value": 10
}
},
{
"name": "Картофель",
"price": 15,
"quantity": 2,
"tax": "vat22",
"unit": "kg",
"discount": {
"type": "percent",
"value": 10
}
},
{
"name": "Кешью",
"price": 1200,
"quantity": 0.1,
"tax": "vat10",
"unit": "kg",
"discount": {
"type": "amount",
"value": 6.55
}
}
]
}
Описание поля purchase
| Параметр | Описание |
|---|---|
| products | Список позиций для печати |
Описание позиций в поле products
| Параметр | Тег | Тип | Описание | Обязательный | Формат | Максимальная длина |
|---|---|---|---|---|---|---|
| name | 1030 | Строка | Наименование позиции. | Да | {С} | 128 |
| price | 1079 | Вещественное | Цена за единицу. | Да | {Ц}.ЦЦ | {Ц} | |
| quantity | 1023 | Вещественное | Количество товаров в позиции. | Да | {Ц}.ЦЦЦ | {Ц} | |
| tax | 1199 | Строка | Налог на позицию. Возможные значения: none - НДС не облагается;vat0 - НДС по ставке 0%;vat5 - НДС чека по ставке 5%;vat7 - НДС чека по ставке 7%;vat10 - НДС чека по ставке 10%;vat22 - НДС чека по ставке 22%;vat105 - НДС рассчитанный 5/105;vat107 - НДС рассчитанный 7/107;vat110 - НДС рассчитанный 10/110;vat122 - НДС рассчитанный 22/122; |
Нет | ||
| unit | Строка | Единица измерения. Доступные значения: piece - штуки, kg - килограммы, g - граммы, l - литры, ml - миллилитры, m2 - квадратные метры. |
Нет | |||
| discount | Структура | Скидка на позицию. | Нет | |||
| type | 1214 | Целое | Признак способа расчета. Для стандартных случаев данный параметр заполнять не следует. Возможные значения: 1 - Полная предварительная оплата до момента передачи предмета расчета;2 - Частичная предварительная оплата до момента передачи предмета расчета;3 - Аванс;4 - Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета;5 - Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит;6 - Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит;7 - Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита); |
Нет | ||
| item_type | 1212 | Целое | Признак предмета расчета. Возможные значения: 1 - Товар;2 - Подакцизный товар;3 - Работа;4 - Услуга;5 - Ставка азартной игры;6 - Выигрыш азартной игры;7 - Лотерейный билет;8 - Выигрыш лотереи;9 - Предоставление результатов интеллектуальной деятельности;10 - Платеж;11 - Агентское вознаграждение;12 - Составной предмет расчета;13 - Иной предмет расчета; |
Нет | ||
| agent_item_type описание пример |
1222 | Массив | Признак агента по предмету расчета. | Нет | ||
| agent_data | 1223 | Структура | Данные агента. | Нет | ||
| supplier_data | 1224 | Структура | Данные поставщика. | Нет | ||
| supplier_inn | 1226 | Строка | ИНН поставщика. Должен быть корректным. | Да, если задано supplier_data | {Ц} | 12 |
| marking_code | 1162 | Строка | Код маркировки, полученный от сканера. Будет разобрано в тег 1162 автоматически. Пример: Переданное значение: 010460043993125621JgXJ5.T\u001d8005112000\u001d930001\u001d923zbrLA==\u001d24014276281 Разобранное значение 1162: 444D042F1F9681784A67584A352E54313132303030 (hex). |
Нет | {С} | 32 |
| country_code | 1230 | Строка | Код страны происхождения товара. | Нет | ЦЦЦ | 3 |
| declaration_number | 1231 | Строка | Номер таможенной декларации. | Нет | {С} | 32 |
| excise_amount | 1229 | Вещественное | Сумма акциза в рублях. | Нет | {Ц}.ЦЦ | {Ц} | |
| additional_detail | 1191 | Строка | Дополнительный реквизит предмета расчета. | Нет | {С} | 64 |
| unit_value | 1197 | Строка | Единица измерения предмета расчета. | Нет | {С} | 16 |
Описание поля discount объекта products
| Параметр | Тип | Описание | Обязательный | Формат | Максимальная длина |
|---|---|---|---|---|---|
| type | Строка | Тип скидки. Возможные значения:amount - абсолютное значение,percent процентное значение. |
Да | ||
| value | Вещественное | Значение скидки. | Да | {Ц}.ЦЦ | {Ц} |
Описание поля agent_data объекта products
| Параметр | Тег | Тип | Описание | Формат | Максимальная длина |
|---|---|---|---|---|---|
| tag1005 | 1005 | Строка | Адрес оператора перевода. | {С} | 256 |
| tag1016 | 1016 | Строка | ИНН оператора перевода. Должен быть корректным. | {Ц} | 12 |
| tag1026 | 1026 | Строка | Наименование оператора перевода. | {С} | 64 |
| tag1075 | 1075 | Массив строк | Телефон оператора перевода. | [+{Ц}] | 19 (для каждого элемента) |
| tag1044 | 1044 | Строка | Операция платежного агента. | {С} | 24 |
| tag1073 | 1073 | Массив строк | Телефон платежного агента. | [+{Ц}] | 19 (для каждого элемента) |
| tag1074 | 1074 | Массив строк | Телефон оператора по приему платежей. | [+{Ц}] | 19 (для каждого элемента) |
Описание поля supplier_data объекта products
| Параметр | Тег | Тип | Описание | Формат | Максимальная длина |
|---|---|---|---|---|---|
| tag1171 | 1171 | Массив строк | Телефон поставщика. | [+{Ц}] | 19 (для каждого элемента) |
| tag1225 | 1225 | Строка | Наименование поставщика. | {С} | 256 |
Описание поля pos
| Параметр | Описание |
|---|---|
| perform | Перед фискализацией принять карту через POS-терминал. Возможные значения: 0 - не использовать, 1 - использовать. |
| slip_count | Количество слип-чеков, которые необходимо распечатать после успешной транзакции по POS-терминалу. Возможные значения: 0, 1, 2. |
Описание поля agent, agent_item_type
| Параметр | Описание |
|---|---|
| bankPaymentAgent | Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом. Возможные значения: 0 - нет, 1 - да. |
| bankPaymentSubagent | Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом. Возможные значения: 0 - нет, 1 - да. |
| paymentAgent | Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом. Возможные значения: 0 - нет, 1 - да. |
| paymentSubagent | Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом. Возможные значения: 0 - нет, 1 - да. |
| attorney | Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным. Возможные значения: 0 - нет, 1 - да. |
| commissioner | Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером. Возможные значения: 0 - нет, 1 - да. |
| agent | Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером. Возможные значения: 0 - нет, 1 - да. |
Описание поля receipt_header_lines
Содержит массив строк:
| Параметр | Тип | Описание |
|---|---|---|
| text | Строка | Строка для печати. |
| align | Строка | Выравнивание текста. Возможные значения: left, center, right. По умолчанию left. |
| text_wrap | Строка | Перенос строки. Возможные значения: no - не переносить, words - переносить по словам. По умолчанию no. |
| char_size_multiply | Целое | Мультипликатор ширины и высоты символов. Возможные значения: 1, 2. По умолчанию 1. |
Описание поля additional_user_detail
| Параметр | Тег | Тип | Описание | Формат | Максимальная длина |
|---|---|---|---|---|---|
| tag1085 | 1085 | Строка | Наименование дополнительного реквизита пользователя. | {С} | 64 |
| tag1086 | 1086 | Строка | Значение дополнительного реквизита пользователя. | {С} | 256 |
Замечания
- Ни одно из полей
card_amount,cash_amount,mc_amountне являются обязательными, но их сумма должна быть не меньше суммы позиций в чеке. Например, если сумма чека по позициям 1000, card_amount = 700, cash_amount = 500 то это означает, что покупатель оплатил покупку по карте на 700 рублей и 500 рублей наличными, сдача при этом будет составлять 200 рублей.
Если оплата была по карте, то в поле card_amount должна быть указана общая сумма, которую клиент оплатил картой и совпадать с суммой позиций в чеке (в примере выше 239.45 рублей).
Любое из этих полей card_amount, cash_amount, mc_amount, prepayment_amount, credit_amount, other_amount может принимать значение #, которое будет сообщать системе, что значение является вычисляемым: # = {сумма всех позиций из products} - (card_amount + cash_amount + mc_amount + prepayment_amount + credit_amount + other_amount).
Данное значение может быть полезно для того, чтобы не вычислять сумму, которую заплатил покупатель по products и не беспокоиться о проблемах с округлением в подсчетах.
В самом простом варианте, если покупка была оплачена, например, по карте, то необходимо заполнить только card_amount = #.
В примере выше, если оплата была по карте на 100, а остальное клиент оплатил наличными, то значения полей можно заполнить как: card_amount = 100, cash_amount = #. В результате cash_amount будет вычислен автоматически и в примере выше будет равен 139.45.
Параметр
modeактуален для принтеров, соответствующих 54-ФЗ. Если этот параметр равенemailилиprint_email, электронный чек будет отправлен покупателю по смс или email (в зависимости от заполненности полейcustomer_phoneиcustomer_email).Функционал аванса/кредита (в соответствии с ФФД 1.05) доступен на принтерах АТОЛ начиная с версии прошивки 3689. Версию прошивки можно посмотреть в личном кабинете Lifepay в разделе Фискализация -> Принтеры.
Параметр
ref_uuidпозволяет сопоставить 2 документа - приход и возврат прихода. Актуален только для запроса возврата прихода (type = refund). В случае, если параметрref_uuidзадан, система попытается найти документ прихода и, если он будет найден и сумма возвратов не превышает суммы прихода, создаст документ возврата прихода. Если осуществляется возврат прихода с параметром pos (perform = 1),ref_uuidявляется обязательным для заполнения для поиска RRN платежа в документе прихода.Признак агента на чек передается только в случае если все позиции чека содержат признак агента по позиции -
agent_item_type, иначе этот реквизит будет проигнорирован.Параметр
tax_systemпозволяет фискализировать продажи в случае нескольких СНО. Если товары продаются по одной СНО, а услуги по другой, необходимо сформировать 2 чека с разными значениямиtax_system. Еслиtax_systemне будет указана в запросе, система применит значение СНО, установленное в личном кабинете Lifepay. Если в личном кабинете СНО не была установлена, будет применена СНО - ОСН.Опция
posсо значениемperform = 1позволяет перед фискализацией принять оплату/возврат по POS-терминалу, в случае успеха будет распечатан фискальный чек прихода (в случаеtype = payment), либо возврата прихода (в случаеtype = refund). Сумма, которая будет отправлена на POS-терминал, берется из параметраcard_amount. Поддерживаемые терминалы: Ingenico IPP* с поддержкой библиотеки arcus2.
Особенности работы с POS-терминалом при удаленной фискализации.
1. В рамках одной смены до сверки на POS терминале при возврате осуществляется попытка отмены, при ее неудаче обрабатывается возврат. 2. Смена на терминале закрывается при снятии z-отчета на принтере, подключенному к тому же микрокомпьютеру. 3. Если смена на терминале не была закрыта в течение 48 часов, сверка осуществляется автоматически спустя 48 часов. 4. В рамках одного микрокомпьютера можно подключить только 1 POS терминал. 5. POS терминалу может не хватать питания только лишь от микрокомпьютера (зависит от блока питания). Нехватка питания выражается в постоянной перезагрузке при попытке оплаты. Поможет подключение отдельного питания к POS-терминалу, либо замена блока питания. 6. Если оплата/возврат по POS терминалу прошла, но чек по каким-либо причинам не распечатался, транзакция откатываться не будет. В зависимости от ошибки принтера, сервер предпримет попытку повторной печати.Если оплата осуществляется через приложение Lifepay, а в личном кабинете в разделе “Фискализация” -> “Сотрудники” разрешена для указанного логина удаленная фискализация и печать на ЧПУ, чек на ЧПУ будет отправлен на устройство с которого был принят платеж.
Список принтеров или логины пользователей, которые подключены к организации можно посмотреть в личном кабинете Lifepay.
Пример успешного ответа:
формат json
Object
(
[code] => 0
[message] =>
[data] => Object
(
[uuid] => dabe3833-43ff-5e5c-a45e-9cff664503ff
)
)
uuid - уникальный идентификатор документа
Пример ответа при ошибке:
формат json
Object
(
[code] => 400
[message] => Ошибка данных.
[data] => Object
(
[purchase] => Array
(
[0] => Ошибка в позиции 1: Значение «Value» не должно превышать 100.
)
)
)
Возможные значения поля code:
500Внутренняя ошибка сервера400Ошибка данных6000Неверный формат данных6009Не удалось найти пользователя по login6010Не удалось найти пользователя по login и apikey6080Облачная фискализация запрещена6095Доступ запрещен
При значении поля “code” = 500 необходимо обратиться в тех поддержку, уточнить причину появления данной ошибки.
Рекомендация:
Если http-код ответа (не путать с полем code) отличен от 200, необходимо повторять запрос с тем же ext_id через некоторые промежутки времени.
Промежутки повтора запроса могут быть, например, такими: 1 минута, 3 минуты, 5 минут, далее – один раз в 10 минут до получения http кода ответа 200.