P54 API

Быстрый старт #

Главное, что нужно понять сразу

Это API «наоборот». Печка54 сама обращается к вашему сайту — вы не вызываете её методы, а реализуете обработчики, которые она будет опрашивать. Все запросы идут методом POST с телом в формате JSON, адреса обработчиков вы задаёте в настройках программы (см. документ «Настройка Печка54»).

Минимальный рабочий сценарий — два обработчика: отдать заказ и принять результат печати. Остальные три подключаются по мере надобности.

Поднимите обработчик выдачи заказов. Печка54 периодически шлёт на него {"action":"order"}, а он отвечает JSON с составом чека — см. получение оплаченных заказов.
Выберите формат чека.Печка54 — полный контроль над каждой строкой чека. Атол.Онлайн — проще, если вы уже интегрированы с фермой Атол.
Поднимите обработчик результата печати. На него придёт код ошибки и ссылка на чек ОФД — см. подтверждение печати. Формально необязателен, но без него вы не узнаете о сбоях.
Пропишите адреса обработчиков в настройках Печки54 и убедитесь, что они отвечают 200 OK.
Добавьте мониторинг.Проверка активности сообщит, что касса отвалилась, Z-отчёт — что смена закрыта.

Сквозной обмен

# 1. Печка54 спрашивает ваш сайт, есть ли заказ для этой кассы
POST https://yoursitename.ru/get-orders
{"action":"order","kkm":"0000000001234567"}

# 2. Ваш сайт отвечает составом чека (формат Печка54)
{"response":{"kkm":"0000000001234567","orderId":"14308", ...}}

# 3. Печка54 печатает чек и сообщает результат
POST https://yoursitename.ru/order-print-result.php
{"action":"<значение из настроек>","kkm":"0000000001234567","resultCode":0, ...}

# 4. Ваш сайт подтверждает приём
HTTP/1.1 200 OK
{"resultCode":0}

Как устроена Печка54 #

Печка54 — сервер печати, который регистрирует кассовые чеки в фискальном регистраторе по требованиям 54-ФЗ для оплат в интернет-магазинах, мобильных приложениях и прочих веб-сервисах.

Программа ставится на компьютер, к которому подключены один или несколько фискальных регистраторов (ФР). Взаимодействие с ФР идёт через драйверы производителя ККМ.

Что делает Печка54

Опрашивает сайты

С заданной периодичностью проверяет один или несколько сайтов на наличие новых оплаченных заказов.

Распределяет по кассам

Направляет заказ на нужный ФР по настройкам и управляет очередью, перекидывая задание на свободную кассу.

Следит за оборудованием

Постоянно проверяет работоспособность подключённых ККМ и сообщает на сайт, если касса отвалилась.

Возвращает чек

После успешной регистрации в ОФД может отправить на сайт ссылку на электронный чек.

Алгоритм взаимодействия

Печка54 опрашивает сайт. Периодичность обращения и адрес задаются в настройках программы.
Сайт передаёт данные об оплаченных заказах в формате JSON. Если данные переданы в неправильном формате, Печка54 отправит POST с информацией об ошибках на отдельный URL, указанный в настройках.
Печка54 формирует задание на регистрацию чека в ФР. Чек фиксируется в фискальном накопителе и передаётся в ОФД. При необходимости можно включить и печать бумажного чека.
Печка54 возвращает ссылку на чек — если отправка в ОФД прошла успешно.

Параллельно Печка54 постоянно обменивается с сайтом состоянием ФР (доступен или нет), может выгружать список подключённых касс и информацию о снятых Z-отчётах.

Совет

Длительность смены на одной кассе не может превышать 24 часа. Смена открывается первым пробитым заказом, время автоматического закрытия задаётся для каждого ФР отдельно в настройках.

Общие правила обмена #

Правило	Как это работает
Инициатор	Всегда Печка54. Ваш сайт только отвечает на её запросы
Метод	Все запросы — `POST`
Формат	Тело запроса и ответа — JSON, кодировка UTF-8
Адреса	Задаются в настройках Печки54. Для проверки активности можно указать разные адреса на подключение и на отключение кассы
Идентификация метода	Поле `action` в теле запроса. По нему обработчик понимает, что от него хотят
Привязка к кассе	Поле `kkm` — регистрационный номер ФР. Присутствует почти во всех запросах
Ответ сайта	`200 OK`. Если ответ содержит тело — оно должно быть корректным JSON
Ошибки	Код возвращается в `resultCode` — см. коды ошибок

Важно

Адрес https://yoursitename.ru в примерах — это ваш сайт, а не сервер СофтБаланс. Подставьте свой домен и свои пути обработчиков.

Все методы списком #

Пять обработчиков, которые вы реализуете у себя. Кликните по строке, чтобы перейти к описанию.

Метод	Адрес обработчика	Назначение
POST	`/kkm-sync.php`	Печка54 передаёт на сайт список своих касс
POST	`/kkm-activity.php`	Касса подключилась или отвалилась
POST	`/z-order.php`	Смена закрыта, снят Z-отчёт
POST	`/get-orders`	Запрос очередного оплаченного заказа на печать
POST	`/order-print-result.php`	Результат печати и ссылка на чек ОФД

Устройства и смены #

Три служебных обработчика: список касс, их состояние и закрытие смены. Все три необязательны — подключайте по мере надобности.

POSTСинхронизация списка устройств#

/kkm-sync.php

После того как все кассы внесены в настройки Печки54, их список можно выгрузить на сайт — чтобы на стороне сайта знать доступные ФР, их налоговые ставки и типы оплаты.

Тело запроса

Поле	Тип	Описание
action		Идентификатор метода. Всегда `"sync"`
data		Список фискальных регистраторов
name		Название ФР из настроек программы
kkm		Регистрационный номер ФР
inn		ИНН из фискального накопителя
fn		Регистрационный номер фискального накопителя
taxes		Доступные налоговые ставки
id		Номер ставки в ККМ — его же передавайте в `tax`
title		Название ставки
typeClose		Доступные типы закрытия чека (способы оплаты)
id		Номер типа закрытия — его же передавайте в `typeClose`
title		Название типа закрытия

Запрос от Печки54

{
  "action": "sync",
  "data": [
    {
      "name": "Касса на выдаче",
      "kkm": "0000000001234567",
      "inn": "7810123456",
      "fn": "9999078900001234",
      "taxes": [
        { "id": 0, "title": "НДС не облагается" },
        { "id": 1, "title": "НДС 20%" },
        { "id": 2, "title": "НДС 10%" }
      ],
      "typeClose": [
        { "id": 0, "title": "Наличными" },
        { "id": 1, "title": "Безналичными" }
      ]
    }
  ]
}

200Сайт принял список. Тело ответа не требуется

POSTПроверка активности кассы#

/kkm-activity.php

Печка54 постоянно опрашивает ФР. Когда состояние связи меняется, она сообщает об этом на сайт — чтобы вы могли, например, приостановить приём оплат или предупредить оператора.

Совет

В настройках можно указать разные адреса для подключения и отключения кассы. Тогда обработчику не придётся разбирать action — событие определяется самим адресом.

Тело запроса

Поле	Тип	Описание
action		Событие: `"KKMConnected"` — связь установлена, `"KKMDisconnected"` — связь потеряна
kkm		Регистрационный номер ФР
device		Модель устройства
title		Название кассы из настроек Печки54

Связь потеряна

{
  "action": "KKMDisconnected",
  "kkm": "0000000001234567",
  "device": "АТОЛ 11Ф",
  "title": "Касса на выдаче"
}

Связь восстановлена

{
  "action": "KKMConnected",
  "kkm": "0000000001234567",
  "device": "АТОЛ 11Ф",
  "title": "Касса на выдаче"
}

200Событие принято. Тело ответа не требуется

POSTПодтверждение снятия Z-отчёта#

/z-order.php

Печка54 умеет вести учёт смен. Смена открывается первым пробитым заказом, закрывается автоматически по времени из настроек ФР. После успешного закрытия на сайт уходит отчёт о смене.

Тело запроса

Поле	Тип	Описание
action		Идентификатор метода. Всегда `"ZReport"`
kkm		Регистрационный номер ФР
inn		ИНН из фискального накопителя
fn		Регистрационный номер фискального накопителя
resultCode		Код результата, `0` — успешно. См. коды ошибок
resultInfo		Текстовое описание результата
closedSession		Номер закрытой смены
sessionSumm		Сумма закрытой смены

Смена закрыта успешно

{
  "action": "ZReport",
  "kkm": "0000000001234567",
  "inn": "7810123456",
  "fn": "9999078900001234",
  "resultCode": 0,
  "resultInfo": "ОК",
  "closedSession": "127",
  "sessionSumm": 45820.50
}

200Отчёт принят. Тело ответа не требуется

Заказы и чеки #

Основная пара обработчиков: отдать заказ на печать и принять результат.

POSTПолучение оплаченных заказов#

/get-orders

Печка54 периодически спрашивает ваш сайт, есть ли заказ для печати на конкретной кассе. Если заказ есть — сайт возвращает состав чека. Поведение при отсутствии заказа в исходной документации не описано; на практике отвечают 200 OK без данных.

Тело запроса

Поле	Тип	Описание
action		Идентификатор метода. Всегда `"order"`
kkm		Регистрационный номер ФР, для которого запрашивается заказ

Запрос от Печки54

{
  "action": "order",
  "kkm": "0000000001234567"
}

Два формата ответа

Сайт отвечает в одном из двух форматов — какой именно, задаётся в настройках Печки54.

Формат Печка54

Максимальная гибкость: вы описываете чек построчно — текст, штрихкоды, изображения, позиции, оплаты, обрезка. Подходит, когда нужен нестандартный чек.

Формат Атол.Онлайн

Совместим с фермой Атол. Проще и короче, но состав чека фиксирован. Подходит для перехода с Атол.Онлайн без переделки бэкенда.

JSONОтвет в формате Печка54#

Чек описывается массивом строк taskTable. Каждая строка — объект с полями data, type и необязательным param.

Обрамление чека

Массив taskTable обязательно начинается строкой открытия чека и заканчивается строкой закрытия — они определяют начало и конец печатаемой информации.

Строка	Значение `type`	Когда применяется
Открытие чека продажи	OpenCheckSell	Обычная продажа
Открытие чека возврата	OpenCheckReturn	Возврат позиции или заказа
Закрытие чека	CloseCheck	Всегда, последней строкой чека

Поля ответа

Поле	Тип	Описание
response		Корневой объект ответа
kkm		Регистрационный номер ФР
orderId		Номер заказа в интернет-магазине. По нему сопоставляется ответ о печати
isInternetPayment		Признак расчёта в интернете, тег 1125. `1` или `0`. По умолчанию `0`
internetPaymentUrl		Адрес места расчётов, тег 1187. Обязателен, если `isInternetPayment = 1`
taskTable		Строки чека по порядку печати
data		Печатаемые данные. Две константы: `Trait` — строка символов «=» во всю ширину, `Dash` — строка «-»
type		Тип строки — см. справочник типов
param		Параметры строки. Набор зависит от `type` — см. справочники String, Registration/Return, оплат

Чек возврата на 500 ₽

{
  "response": {
    "kkm": "0000000001234567",
    "orderId": "14308",
    "isInternetPayment": 1,
    "internetPaymentUrl": "https://yoursitename.ru",
    "taskTable": [
      { "data": "", "type": "OpenCheckReturn" },
      { "data": "79219056607", "type": "ClientContact" },
      {
        "data": "Лицензия Печка54",
        "type": "Return",
        "param": { "price": 500.00, "quantity": 1, "tax": 3 }
      },
      {
        "data": "",
        "type": "Payment",
        "param": { "summ": 500.00, "typeClose": 0 }
      },
      { "data": "", "type": "CloseCheck" }
    ]
  }
}

Чек продажи с оформлением: заголовок, позиции, разделитель

{
  "response": {
    "kkm": "0000000001234567",
    "orderId": "14309",
    "isInternetPayment": 1,
    "internetPaymentUrl": "https://yoursitename.ru",
    "taskTable": [
      { "data": "", "type": "OpenCheckSell" },
      {
        "data": "ИНТЕРНЕТ-ЗАКАЗ №14309",
        "type": "String",
        "param": { "alignment": "Center", "bold": true, "dblHeight": true }
      },
      { "data": "Dash", "type": "String" },
      { "data": "user@example.com", "type": "ClientContact" },
      {
        "data": "Носки с грозовыми молниями, 2 пары",
        "type": "Registration",
        "param": { "price": 799.00, "quantity": 2, "tax": 1, "department": 1 }
      },
      {
        "data": "",
        "type": "Payment",
        "param": { "summ": 1598.00, "typeClose": 1 }
      },
      { "data": "", "type": "CloseCheck" },
      { "data": "", "type": "Cut" }
    ]
  }
}

JSONОтвет в формате Атол.Онлайн#

Формат совместим с фермой Атол — чтобы переход на Печку54 (или обратно) не требовал переделки бэкенда.

Поля ответа

Поле	Тип	Описание
timestamp		Дата и время документа в формате `dd.mm.yyyy HH:MM:SS`
external_id		Номер заказа в интернет-магазине
isInternetPayment		Признак расчёта в интернете, тег 1125. `1` или `0`
internetPaymentUrl		Адрес места расчётов, тег 1187. Обязателен при `isInternetPayment = 1`
service		Служебный раздел
inn		ИНН из фискального накопителя
payment_address		Адрес места расчётов. Печкой54 не обрабатывается
callback		URL для ответа после обработки. Печкой54 не обрабатывается
receipt		Информация о чеке
attributes		Атрибуты чека
sno		Система налогообложения. Печкой54 не обрабатывается
email		Электронная почта покупателя
phone		Телефон покупателя
items		Товары в чеке. От 1 до 100 позиций
name		Наименование товара
price		Цена за единицу, копейки через точку
quantity		Количество
sum		Сумма позиции. Если меньше `price × quantity`, разница считается скидкой
tax		Номер налоговой ставки в ККТ. Отличается от одноимённого поля Атол.Онлайн
tax_sum		Сумма налога позиции. Отличается от одноимённого поля Атол.Онлайн
total		Итог чека: до 8 знаков целой части и до 2 дробной
payments		Оплаты по чеку
type		Способ оплаты — номер типа закрытия из `typeClose`. В файле `pechka54.txt` тип объявлен как `object`, но пример там же передаёт число
sum		Сумма оплаты

Чек продажи на 1 598 ₽

{
  "timestamp": "12.04.2026 06:15:06",
  "external_id": "14308",
  "isInternetPayment": 1,
  "internetPaymentUrl": "https://yoursitename.ru",
  "service": {
    "inn": "7810123456",
    "payment_address": "",
    "callback": ""
  },
  "receipt": {
    "attributes": {
      "sno": "",
      "email": "user011@example.ru",
      "phone": "79111023004"
    },
    "items": [
      {
        "name": "Комплект из 2 пар носков с грозовыми молниями",
        "price": 799.00,
        "quantity": 2,
        "sum": 1598.00,
        "tax": 1,
        "tax_sum": 266.33
      }
    ],
    "total": 1598.00,
    "payments": [
      { "type": 1, "sum": 1598.00 }
    ]
  }
}

Примечание

Поля sno, payment_address и callback оставлены для совместимости с Атол.Онлайн, но Печкой54 не обрабатываются — можно передавать пустыми.

POSTПодтверждение печати чека#

/order-print-result.php

После печати Печка54 сообщает результат и ссылку на электронный чек. Обработчик необязателен, но именно он позволяет вести на сайте историю чеков и ловить сбои.

Тело запроса

Поле	Тип	Описание
action		Идентификатор метода. Конкретное значение в исходной документации не указано — уточните в поддержке
kkm		Регистрационный номер ФР
inn		ИНН из фискального накопителя
fn		Регистрационный номер фискального накопителя
resultCode		Код результата печати, `0` — успешно. См. коды ошибок
resultInfo		Текстовое описание результата
shiftNumber		Номер смены, в рамках которой пробит чек
OFDLink		Ссылка на веб-версию чека на сайте ОФД. Формат задаётся в настройках ККМ, передаётся в кодировке base64

Чек напечатан успешно

{
  "action": "<значение из настроек>",
  "kkm": "0000000001234567",
  "inn": "7810123456",
  "fn": "9999078900001234",
  "resultCode": 0,
  "resultInfo": "ОК",
  "shiftNumber": "127",
  "OFDLink": "aHR0cHM6Ly9vZmQucnUvY2hlY2s/aWQ9MTIzNDU2Nzg5"
}

Печать не удалась

{
  "action": "<значение из настроек>",
  "kkm": "0000000001234567",
  "inn": "7810123456",
  "fn": "9999078900001234",
  "resultCode": 4,
  "resultInfo": "Нет бумаги в устройстве",
  "shiftNumber": "127",
  "OFDLink": ""
}

200Результат принят. Тело ответа не требуется

Справочник: типы строк чека #

Значения поля type в массиве taskTable формата Печка54.

Обрамление чека

Значение	Что делает
OpenCheckSell	Открытие чека продажи
OpenCheckReturn	Открытие чека возврата
CloseCheck	Закрытие чека
CancelCheck	Отмена чека

Позиции и деньги

Значение	Что делает
Registration	Регистрация продажи в фискальной памяти. Параметры — price, quantity и другие
Return	Возврат позиции на сумму `price` и количество `quantity`. Сумма чека печатается только при параметре `enableCheckSumm`
Payment	Оплата на сумму `summ`. Отрицательное значение `summ` означает сторно
CashIncome	Внесение денег на сумму `summ`
CashOutcome	Выплата денег на сумму `summ`

Текст и оформление

Значение	Что делает
String	Печать текста из `data` с оформлением из param
BarCode	Печать штрихкода. Поддерживается не всеми моделями принтеров
Image	Печать изображения. В `data` передаётся URL картинки, лежащей на той же машине, что и сервер печати
ClientContact	Адрес или телефон клиента из `data`. Может быть пустым. Фискальный документ не печатается, если `printDoc = false`
PrintHeader	Печать шапки документа
PrintFooter	Печать подвала документа
Cut	Обрезка чека

Служебные

Значение	Что делает
Report	Печать фискального отчёта. Тип отчёта задаётся параметром `reportType`
SyncTime	Синхронизация времени

Справочник: param для type = String #

Оформление печатаемого текста, штрихкодов и отчётов.

Параметр	По умолч.	Описание
font	`0`	Шрифт, значения от 0 до 3
bold	`false`	Жирный текст
italic	`false`	Наклонный текст
dblHeight	`false`	Двойная высота текста
underLine	`false`	Подчёркнутый текст
overLine	`false`	Надчёркнутый текст
negative	`false`	Негатив
charRotation	`0`	Поворот текста: 0 — 0°, 1 — 90°, 2 — 180°, 3 — 270°
wrap	`true`	Переносить строку, если текст не помещается по ширине чека
alignment	—	Выравнивание: `Left`, `Center`, `Right`
newLine	`true`	Перевод каретки после печати значения
lineSpacingMax	`false`	Максимальное межстрочное расстояние вместо минимального
barCodeHeight	`50`	Высота штрихкода в миллиметрах
barCodeType	`EAN13`	Кодировка штрихкода: `EAN13` или `Code39`
barCodePrintText	`false`	Печатать текст под штрихкодом
printDoc	`true`	Печатать ли фискальный документ
reportType	—	Тип отчёта для `type = Report`: 1 — Z-отчёт с гашением, 2 — X-отчёт, 7 — по секциям, 8 — по кассирам, 10 — почасовой

Примечание

В исходной документации тип штрихкода записан как Сode39 — с русской «С» в начале. Здесь исправлено на латинское Code39.

Справочник: param для Registration и Return #

Параметры товарной позиции чека.

Параметр	По умолч.	Описание
price	`0`	Цена товара, копейки через точку
quantity	`0`	Количество товара
department	`1`	Отдел, на который пробивается позиция
tax	—	Номер налоговой ставки в ККМ из `taxes`. Если не передан, ставка в ФР не передаётся
discountType	—	Тип скидки: `0` — в рублях, `1` — в процентах
discountValue	—	Значение скидки

Справочник: param для оплат и денежных операций #

Применяется для type = Payment, CashIncome, CashOutcome.

Параметр	Тип	Описание
summ		Сумма операции. Единственный параметр, который может быть отрицательным — например `-20.12` для сторнирования в операции `Payment`
typeClose		Тип оплаты (тип закрытия) из `typeClose`. По документации: `0` — оплата наличными, `1` — любой другой тип

Справочник: коды ошибок #

Значения поля resultCode.

Код	Константа	Что означает
0	SUCCESS	Всё хорошо, ошибок нет
1	MISSED_PARAMETERS	Ошибка в переданных параметрах
2	UNKNOWN_ACTION	Неизвестное значение поля `action`
3	PARAMETERS_ERROR	Переданы не все обязательные параметры
4	HANDLING_ERROR	Любая другая ошибка. Разработчик может ввести собственный классификатор поверх этого кода

Печка54 — API v1. Справочник подготовлен на основе официального описания API.

Поддержка: ireca@softbalance.ru · СофтБаланс