API Печка54

FORMAT: 1A HOST: https://yoursitename.ru ## Назначение программы Печка54 В связи с изменениями Федерального закона от 22.05.2003 №54 «О применении контрольно-кассовой техники при осуществлении наличных денежных расчетов и (или) расчетов с использованием платежных карт» появилась потребность в создании программного продукта, позволяющего регистрировать чеки при оплате заказов в интернет-магазинах, мобильных приложениях и прочих веб-сервисах. Программный продукт Печка54 – это сервер печати, который обеспечивает передачу информации с сайта (приложения) об оплаченных заказах и регистрацию кассового чека в ФР в соответствии с требованиями закона 54-ФЗ. ## Принцип работы Печка54 устанавливается на компьютере, к которому подключаются один или несколько ФР. Взаимодействие Печки54 с ФР осуществляется через драйвера, распространяемые производителем ККМ. С заданной периодичностью Печка54 опрашивает один или несколько сайтов на предмет наличия новых оплаченных заказов. В случае появления нового заказа, сайт пересылает информацию для регистрации кассового чека. При успешной регистрации чека в ОФД Печка54 может отправить на сайт ссылку на электронный чек. В соответствии с заданными настройками, поступивший заказ перенаправляется на соответствующий ФР. Печка54 может управлять очередью заказов перенаправляя задание на свободный ФР. Печка54 производит постоянный мониторинг работоспособности подключенных ККМ. В случае получения сигнала о неработоспособности ККМ, Печка54 передает соответствующую информацию на сайт. Взаимодействие Печки54 с сайтом осуществляется POST запросами к указанным в настройках программы URL страницам. Сайт возвращает данные в формате JSON. В ответ на полученные данные Печка54 присылает код подтверждения правильности полученных данных либо код ошибки. ## Алгоритм взаимодействия Интернет-магазина и Печка54 1. Печка54 отправляет POST-запросы к сайту. Периодичность обращения и адрес сайта указываются в настройках. 2. Сайт передает данные об оплаченных заказах в формате JSON. В случае если данные переданы в неправильном формате, то по указанному в настройках URL будет отправлен POST-запрос с информацией об ошибках. 3. При успешном получении данных с сайта, Печка54 формирует задание на регистрацию чека в ФР. Чек фиксируется в ФН и передается в ОФД. При необходимости можно включить печать бумажного чека. 4. Если отправка чека в ОФД прошла успешно, Печка54 отправляет на сайт информацию с ссылкой на электронный чек. Печка54 постоянно обменивается с сайтом состоянием ФР (доступен/не доступен), может выгружать на сайт список подключенных касс и информацию о снятых Z-отчетах. ## Описание методов [https://yoursitename.ru/methods] Любое взаимодействие Печка54 и сайта происходит с помощью POST запросов, в которых данные передаются в формате JSON. Инициализатором обмена данными является Печка54. Ознакомится с настройками можно в руководстве пользователя ## Синхронизация списка устройств [https://yoursitename.ru/kkm-sync.php] После внесения всех касс в настройках Печки54 вы можете загрузить информацию о ваших ФР на сайт. Для этого Печка54 отправляет POST запрос на URL, указанный в настройках программы. ### Параметры запроса [POST] + Attributes (object) + action: "sync" (string) - Параметр отвечающий за идентификацию метода + data (array) - Массив, в котором передается информация о ФР, которые необходимо синхронизировать с сайтом. + name (string) - Название, указанное для ФР в настройках программы + kkm (string) - Регистрационный номер ФР + inn (string) - ИНН из фискального накопителя + fn (string) - Регистрационный номер фискального накопителя + taxes (array) - Массив доступных идентификаторов налогов - (object) - массив с идентификаторами налогов + id (number) - Уникальный номер налога в системе + title (string) - Название налоговой ставки + typeClose (array) - Массив доступных типов закрытия - (object) - массив с типами закрытия + id (number) - Уникальный номер типа закрытия + title (string) - Название типа закрытия + Request (application/json) { "action": "sync" "data": { "name": "Название кассы, заданное в настройках", "kkm": "XXXXXXXXXXXX", "inn": "XXXXXXXXXXXX", "fn": "XXXXXXXXXXXX", "taxes": [ { "id": 0, "title": "XXXXXXXXXXXX" }, { "id": 1, "title": "НДС 18%" } ], "typeClose": [ { "id": 0, "title": "Наличными" }, { "id": 1, "title": "Наличными" } ] } } + Response 200 ## Поверка активности кассы [https://yoursitename.ru/kkm-activity.php] Сервер печати Печка54 может опрашивать ФР для проверки связи с ней. В случае изменения в состоянии работы ФР Печка54 может отправить POST запрос на URL, указанный в настройках. Вы можете указать разные URL для обработки POST-запросов при установлении или при отключении связи с кассой (см документацию по настройке Печка54). ### Параметры запроса [POST] + Attributes (object) + action: "KKMDisconected" (string) - Параметр отвечающий за идентификацию метода: KKMDisconected – отключение, KKMConected - подключение + kkm (string) - Регистрационный номер ФР + device (string) - Название устройства + title (string) - Название кассы из настроек Печки54 + Request (application/json) { "action": "KKMDisconected", "kkm": " XXXXXXXXXXXX ", "device": "Атол 11Ф", "title": "Название кассы, заданное в настройках" } + Request (application/json) { "action": "KKMConected", "kkm": " XXXXXXXXXXXX ", "device": "Атол 11Ф", "title": "Название кассы, заданное в настройках" } + Response 200 ## Подтверждение снятия Z-отчета [https://yoursitename.ru/z-order.php] Настройки сервера печати Печка54 позволяют вести учет смен. Длительность каждой смены на одном ККМ не должна превышать 24 часа. Открытие смены происходит с первым «пробитым» заказом. Время автоматического закрытия смены (снятие Z-отчета) для каждого ФР устанавливается в настройках отдельно. В случае успешного закрытия смены на URL, указанный в настройках, может быть отправлен POST запрос ### Параметры запроса [POST] + Attributes (object) + action: "ZReport" (string) - Параметр отвечающий за идентификацию метода + kkm (string) - Регистрационный номер ФР + inn (string) - ИНН из фискального накопителя + fn (string) - Регистрационный номер фискального накопителя + resultCode: 0 (number) - Код ошибки печати + resultInfo: "ОК" (string) - Пользовательское описание ошибки + closedSession (string) - Номер закрытой смены + sessionSumm (number) - Сумма закрытой сессии + Request (application/json) { "action": "ZReport", "kkm": "XXXXXXXXXXXX", "fn": "XXXXXXXXXXXX", "resultCode": "0", "resultInfo": "ОК" } + Response 200 ## Получение информации об оплаченных заказах [https://yoursitename.ru/get-orders] Для получения заказов, которые должны быть переданы в ФР, Печка54 делает POST-запрос на URL, указанный в настройках. В ответ на запрос должен быть сформирован JSON с данными о заказе, которые необходимо отправить на печать. Сервер-печати Печка54 поддерживает два формата передачи данных на печать: Печка54 и Атол.Онлайн. ### Параметры запроса [POST] + Attributes (object) + action: "order" (string) - Параметр отвечающий за идентификацию метода + kkm (string) - Регистрационный номер ФР + Request (application/json) { "action": "order", "kkm": "XXXXXXXXXXXX" } + Response 200 ### Формат Печка54 [POST] Этот формат предоставляет максимальную гибкость для формирования состава и оформления чека. В запросе обязательно должны быть переданы два объекта с типом OpenCheckSell и CloseCheck. Данные параметры определяют начала и конец печатаемой информации в чеке. + Attributes (object) + response (object) + kkm (string) - Регистрационный номер ФР + OrderId (string) - Номер заказа в интернет-магазине. Используется для корректной обработки ответа о печати чека + taskTable: (array) - Массив данных о строчках чека + object + data - Данные, которые будут напечатаны в строке. Так же может быть присвоено две константы: Trait - во всю ширину чека будут распечатаны символы «=», Dash – во всю ширину чека будут распечатаны символы «-» + type - Определяет тип строки из поля «data». Может принимать следующие значения + param - Параметры печатаемых данных из поля «data» для определённого типа указанного в поле «type». Для разных значений поля "type" могут применятся разные значения поля "param" String, Registration или Return, CashIncome, CashOutcome или Payment + Request (application/json) { "action": "order", "kkm": "XXXXXXXXXXXX" } + Response { "response": { "kkm": "XXXXXXXXXXXX", "OrderId": "14308", "taskTable": [ { "data": "", "type": "OpenCheckReturn" }, { "data": "79219056607", "type": "ClientContact" }, { "data": "Лицензия Печки54", "param": { "price": "500.00", "quantity": 1, "tax": "3" }, "type": "return" }, { "data": "", "Param": { "Summ": "500.00", "TypeClose": 3 }, "type": "Payment" }, { "data": "", "type": "CloseCheck" } ] } } ### Формат Атол.Онлайн [POST] В целях обеспечения простоты перехода пользователей Атол.Онлайн на Печку54 или с Печки54 на Атол.Онлайн обеспечена поддержка формата обмена данными с фермой Атол. + Attributes (object) + timestamp: '12.04.2017 06:15:06' (string) - Дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS» · dd – День месяца. Формат DD. Возможные значения от «01» до «31». mm – Месяц. Формат MM. Возможные значения от «01» до «12». yyyy – Год. Формат YYYY. Допустимое количество символов – четыре. HH – Часы. Формат HH. Возможные значения от «00» до «24». · MM – Минуты. Формат MM. Возможные значения от «00» до «59». SS – Секунды. Формат SS. Возможные значения от «00» до «59». + external_id: (string) - Номер заказа в интернет-магазине + service (object) - Служебный раздел + inn - ИНН из фискального накопителя + payment_address - Адрес места расчетов. Используется для предотвращения ошибочных регистраций чеков на ККТ зарегистрированных с другим адресом места расчёта (сравнивается со значением в ФН). ДАННОЕ ПОЛЕ НЕ ОБРАБАТЫВАЕТСЯ ПРИ РАБОТЕ С ПРОГРАММОЙ ПЕЧКА54 + callback - URL, на который необходимо ответить после обработки документа. Если поле заполнено, то после обработки документа (успешной или не успешной фискализации в ККТ), ответ будет отправлен POST запросом по URL указанному в данном поле. ДАННОЕ ПОЛЕ НЕ ОБРАБАТЫВАЕТСЯ ПРИ РАБОТЕ С ПРОГРАММОЙ ПЕЧКА54 + receipt (object) - Информация о чеке + attributes (object) - Атрибуты чека + sno (string) - Система налогообложения. Перечисление со значениями: osn – общая СН, usn_income – упрощенная СН (доходы), usn_income_outcome – упрощенная СН (доходы минус расходы), envd – единый налог на вмененный доход, esn – единый сельскохозяйственный налог, patent – патентная СН. ДАННОЕ ПОЛЕ НЕ ОБРАБАТЫВАЕТСЯ ПРИ РАБОТЕ С ПРОГРАММОЙ ПЕЧКА54 + email (string) - Электронная почта покупателя + phone (string) - Телефон покупателя + items (array) - Товары в чеке. Ограничение по количеству от 1 до 100 + object + name (string) - Наименование товара + price (number) - Цена товара. Копейку указываются через точку + quantity (number) - Количество + sum (number) - Сумма позиции в рублях. Если значение sum меньше значения (price*quantity), то разница является скидкой на позицию. + tax (number) - Устанавливает номер налога в ККТ. ДАННОЕ ПОЛЕ ОТЛИЧАЕТСЯ ОТ ПОДОБНОГО В АТОЛ.ОНЛАЙН + tax_sum (number) - Сумма налога позиции. ДАННОЕ ПОЛЕ ОТЛИЧАЕТСЯ ОТ ПОДОБНОГО В АТОЛ.ОНЛАЙН + total (number) - Итоговая сумма чека в рублях с заданным в CMS округлением: целая часть не более 8 знаков, дробная часть не более 2 знаков. + payments (array) - Информация об оплате + object + type (object) - Способ оплаты + sum (number) - Сумма к оплате в рублях. + Request (application/json) { "action": "order", "kkm": "XXXXXXXXXXXX" } + Response 200 { "timestamp": "12.04.2017 06:15:06", "external_id": "14308", "service": { "inn": "7755555217", "callback_url": "", "payment_address": "" }, "receipt": { "attributes": { "sno": "", "email": "user011@domen.ru", "phone": "9111023004" }, "items": [ { "name": "Комплект из 2 пар носков c грозовыми молниями", "price": 799, "quantity": 1 "sum": 799, "tax": 1, "tax_sum": «», } ], "total": 1598, "payments": [ { "sum": 1598, "type": 2 } ] } } ## Подтверждение печати чека [https://yoursitename.ru/order-print-result.php] После выполнения печати Печка54 отправляет POST запрос на URL указанный в настройках. В данном запросе будет передана информация о ссылке на чек. Данный запрос не обязателен, но его использование рекомендуется. Эти данные позволят в рамках сайта вести информацию о сбоях и состоянии чеков. ### Параметры запроса [POST] + Attributes (object) + action (string) - Параметр отвечающий за идентификацию метода + kkm (string) - Регистрационный номер ФР + inn (string) - ИНН из фискального накопителя + fn (string) - Регистрационный номер фискального накопителя + resultCode: 0 (number) - Код ошибки печати + resultInfo: "Ок" (string) - Пользовательское описание ошибки + shiftNumber (string) - Номер смены в рамках которой был пробит чек + OFDLink (string) - Ссылка на web версию чека на сайте ОФД. Формат ссылки задается в настройках ККМ. При передаче ссылка обфусцирована base64 ## Справочники [/] ### Возможные значения для определения типа строки в формате ответа Печка54 [POST] + Attributes + String - будет напечатан текст из поля data с форматирование по полю param + BarCode - Печать штрих кода (поддерживается не всеми моделями принтеров) + Image - в поле Data нужно передать URL изображения, которое находится на том же машине где и сервер печати + Registration - регистрация продажи в фискальной памяти + CloseCheck - закрыть чек + CancelCheck - отмена чека + OpenCheckSell - открытие чека продажи + Payment - Оплата на сумму Summ. Оплата наличными TypeClose -0, если нет TypeClose -1. Если значение Summ отрицательное, то вместо оплаты будет сторно на эту сумму. + OpenCheckReturn - открытие чека возврата + Return - возврат позиции на сумму Price и количество Quantity. Сумма чека будет напечатана только если есть параметр EnableCheckSumm + CashIncome - Внесение денег на сумму параметра Summ + CashOutcome - Выплата денег на сумму параметра Summ + ClientContact- Адрес или телефон клиента задается в значении data. Может быть пустым. Фискальный документ не будет напечатан в случае если PrintDoc = 0 (false) + Report - печать фискальных отчетов (тип отчета задается в параметр ReportType) + SyncTime - синхронизация времени + PrintHeader - печать подвала документа + PrintFooter - печать шапки документа + Cut - обрезка ### Возможные значения поля param в случае если "type": String [POST] + Attributes + Font: 0 (number) - Может принимать значение от 0-3 + Bold: false (boolean) - Жирный текст + Italic: false (boolean) - Наклонный текст + DblHeight: false (boolean) - Двойная высота текста + UnderLine: false (boolean) - Подчеркнутый текст + OverLine: false (boolean) - Надчеркнутый текст + Negative: false (boolean) - Негатив + CharRotation: 0 (number) - Поворот текста на определенный градус. Возможные значения: 0 - 0 градусов, 1 – 90 градусов, 2 – 180 градусов, 3 – 270 градусов + Wrap: true (boolean) - Если строка не поместилась по ширине чека, то автоматически будут расставлены знаки переноса и текст будет распечатан полностью на необходимом количестве строк. + Alignment (string) - Выравнивание текста. Возможные значения: Left – выравнивание по левому краю, Center – выравнивание по центру, Right– выравнивание по правому краю + NewLine: true (boolean) - Перенос каретки на новую строку после печати значения из поля data + LineSpacingMax: false (boolean) - Расстояние между строками минимальное или максимальное + BarCodeHeight: 50 (number) - Высота штрихкода в мм + BarCodeType: 'EAN13' (string) - Тип кодировки штрих кода. Может принимать значения:EAN13, Сode39 + BarCodePrintText: false (boolean) - Печать текста в штрих коде + PrintDoc: true (boolean) - Требуется ли печатать фискальный документ + ReportType (number) - Типа отчета. Возможные значения:1 - Z-отчет (с гашением), 2 - Х-отчет, 7 - Отчет по секциям, 8 - Отчет по кассирам, 10 - Отчет почасовой ### Возможные значения поля param в случае если "type": Registration или Return [POST] + Attributes + Price: 0 (number) - Цена товара. Копейку указываются через точку + Quantity: 0 (number) - Количество товара + Department: 1 (number) - Отдел, на который пробивается чек + Tax (number) - Номер налоговой ставки в ККМ. Если значение не передано в параметрах, то налоговая ставка не передается в ФР + DiscountType (number) - Тип скидки. Возможные значения:0 – скидка в рублях, 1 – скидка в процентах + DiscountValue (number) - Значение скидки ### Возможные значения поля param в случае если "type": CashIncome, CashOutcome или Payment [POST] + Attributes + Summ: 0 (number) - Сумма денежной операции. Единственный параметр, который может принимать отрицательное значение. Пример Summ=-20.12 (Отрицательное значение может применяться для сторнирования в операции type=Payment) + TypeClose: 0 (number) - Тип оплаты (Тип закрытия) ### Возможные типы ошибок [POST] + Parameters + 0 - SUCCESS. Все хорошо. Ошибок нет. + 1 - MISSED_PARAMETERS. Ошибка в переданных параметрах + 2 - UNKNOWN ACTION. + 3 - PARAMETERS ERROR. Переданы не все параметры + 4 - HANDLING_ERROR. Любая другая ошибка (разработчик может вводить свой классификатор ошибок).