Кассовый аппарат отказывается печатать чек из JSON-файла чаще всего по одной из трёх причин: нарушена структура задания, не установлен или не запущен драйвер ККТ, либо файл сохранён в неправильной кодировке. Прежде чем искать ошибку в коде, проверьте, что касса видна в драйвере и проходит тест связи — без этого никакой JSON до устройства просто не дойдёт.
Под «печатью чека из JSON» обычно понимают отправку на фискальный регистратор или онлайн-кассу структурированного задания в формате JSON, которое содержит тип операции, позиции, суммы и реквизиты. Такой подход используется при интеграции кассы с учётными системами, самописными скриптами и веб-сервисами. В этой статье разберём, как устроено JSON-задание, какие инструменты нужны для его отправки и как диагностировать типовые сбои.
Что представляет собой JSON-задание для печати чека
JSON-задание — это текстовый файл или строка, в которой описаны все параметры будущего чека: тип операции (приход, возврат прихода, расход), список товарных позиций с ценами и количеством, способ расчёта, ставки НДС и реквизиты кассира. Кассовое ПО или драйвер парсит эту структуру и преобразует её в команды фискального накопителя.
Важно понимать: единого универсального стандарта JSON-чека не существует. У каждого производителя ККТ и каждого драйвера свой набор полей и свои названия параметров. Схема, которая работает с оборудованием АТОЛ, не обязательно совпадёт со схемой для Штрих-М или Меркурий. Поэтому первым делом найдите официальную документацию на JSON-интерфейс именно вашего драйвера — обычно она называется «описание формата заданий» или «JSON API».
Типовой минимальный набор полей задания выглядит так:
- 🧾 Тип документа — открытие смены, чек, закрытие смены, отчёт о состоянии расчётов;
- 🛒 Позиции чека — наименование товара, цена, количество, налоговая ставка;
- 💳 Оплата — наличный или безналичный расчёт, сумма по каждому виду оплаты;
- 👤 Кассир — ФИО и, если требуется, ИНН оператора;
- 📧 Реквизиты покупателя — телефон или email для отправки электронного чека, если он нужен.
Подготовка: драйвер ККТ и проверка связи
Прежде чем отправлять JSON, убедитесь, что касса физически подключена и определяется системой. Установите актуальную версию драйвера ККТ с официального сайта производителя и запустите тест связи — эта функция есть в штатной утилите настройки практически любого драйвера. Если тест связи не проходит, дальнейшие шаги бессмысленны: проверяйте кабель, порт и параметры подключения.
Для сетевых касс дополнительно проверьте, что компьютер и ККТ находятся в одной сети и порт кассы доступен. Для USB-подключения убедитесь, что в диспетчере устройств нет конфликтов и порт определился корректно.
⚠️ Внимание: не отправляйте тестовые задания на боевую кассу с реальным фискальным накопителем — каждый чек фискализируется и уходит в ОФД. Для отладки используйте режим эмуляции, если он предусмотрен вашим драйвером, или тестовый фискальный накопитель.
Структура JSON-файла: пример и правила оформления
Конкретные имена полей зависят от драйвера, но общие принципы одинаковы: файл должен быть валидным JSON, содержать корневой объект задания и строго соответствовать схеме производителя. Условный упрощённый пример структуры (не привязанный к конкретному вендору):
{
"type": "sell",
"operator": { "name": "Иванов И.И." },
"items": [
{
"name": "Товар 1",
"price": 100.00,
"quantity": 2,
"tax": "vat20"
}
],
"payments": [
{ "type": "cash", "sum": 200.00 }
]
}
Обратите внимание на детали, которые чаще всего становятся причиной отказа:
- 📄 Кодировка файла — сохраняйте JSON в UTF-8 без BOM, если документация не требует иного;
- 🔢 Типы данных — суммы передавайте числом, а не строкой, если того требует схема; лишние кавычки ломают парсинг;
- ➗ Разделитель дробной части — точка, а не запятая, это стандарт JSON;
- 🚫 Лишние поля — некоторые драйверы отклоняют задание при наличии неизвестных параметров.
Сумма оплаты должна сходиться с итогом по позициям с точностью до копейки. Расхождение хотя бы в одну копейку — типичная причина отказа кассы закрывать чек.
Способы отправки JSON на печать
Существует несколько рабочих сценариев в зависимости от вашего оборудования и ПО. Выберите тот, который соответствует вашей связке «касса + драйвер».
Первый способ — через веб-сервер драйвера. Многие современные драйверы ККТ поднимают локальный HTTP-сервис, принимающий JSON-задания POST-запросом. В этом случае отправка сводится к простому запросу, например через curl:
curl -X POST http://127.0.0.1:PORT/api/task -H "Content-Type: application/json" -d @check.jsonНомер порта и путь endpoint возьмите из документации вашего драйвера — они различаются между производителями и версиями. После отправки сервер обычно возвращает идентификатор задания, по которому отдельным запросом проверяется статус выполнения.
Второй способ — через файл-обменник. Некоторые драйверы отслеживают указанную папку: вы кладёте туда JSON-файл, драйвер забирает его, печатает чек и складывает рядом файл с результатом. Этот вариант удобен для интеграции с программами, которые умеют только сохранять файлы на диск.
Третий способ — через COM-объект или библиотеку драйвера из вашего кода (1С, Python, C# и т.д.). Здесь JSON либо передаётся в специальный метод целиком, либо вы формируете чек вызовами отдельных методов драйвера.
☑️ Перед отправкой JSON-чека проверьте
Диагностика типичных ошибок
Если чек не печатается, двигайтесь от простого к сложному. Сначала проверьте, открыта ли смена — многие кассы отклоняют чек при закрытой смене, и это одна из самых частых причин «молчания» аппарата. Затем посмотрите ответ драйвера: корректные реализации возвращают код ошибки и текстовое описание, по которым можно понять, на каком этапе задание отклонено.
| Симптом | Вероятная причина | Что проверить |
|---|---|---|
| Задание не принимается вообще | Невалидный JSON или неверный endpoint | Прогнать файл через валидатор, сверить адрес и порт |
| Задание принято, но чек не выходит | Ошибка на уровне кассы | Запросить статус задания, проверить ленту и смену |
| Ошибка по сумме | Оплата не равна итогу позиций | Пересчитать итог, проверить округление |
| Крякозябры в наименованиях | Неверная кодировка файла | Пересохранить в UTF-8 |
| Отказ из-за неизвестного поля | Параметр не поддерживается версией драйвера | Сверить схему с документацией вашей версии |
⚠️ Внимание: после обрыва связи в момент печати не отправляйте задание повторно вслепую — сначала запросите статус последнего документа. Иначе возможна печать дубля чека, который уже ушёл в фискальный накопитель.
Держите под рукой эталонный JSON-файл с минимальным чеком из одной позиции. Если сложное задание не проходит, отправьте эталонное: если и оно падает — проблема в связи или кассе, а не в структуре вашего файла.
Печать чека без фискализации: чисто техническая сторона
Иногда под запросом «распечатать чек JSON» скрывается другая задача: вывести на обычный принтер данные из JSON-файла в виде, похожем на чек — например, для внутреннего учёта или тестового макета. Здесь фискальный аппарат не нужен: достаточно скрипта, который читает JSON и формирует печатную форму.
Простейший вариант на Python — прочитать файл и сформировать текст для вывода:
import json
with open("check.json", encoding="utf-8") as f:
data = json.load(f)
total = 0
for item in data["items"]:
line_sum = item["price"] * item["quantity"]
total += line_sum
print(f'{item["name"]} x{item["quantity"]} = {line_sum:.2f}')
print(f"ИТОГО: {total:.2f}")
Полученный текст можно направить на принтер штатными средствами ОС или оформить в HTML-шаблон и распечатать из браузера. Такой документ не является фискальным чеком и не заменяет его в расчётах с покупателями.
Почему нельзя просто «распечатать» фискальный чек на обычном принтере
Фискальный чек формируется связкой ККТ и фискального накопителя: данные подписываются, получают фискальный признак и номер ФД, а копия передаётся оператору фискальных данных. Распечатка из обычного принтера не содержит этих реквизитов и юридически чеком не является. Для расчётов с покупателями используйте только зарегистрированную кассу.
Успешная печать чека из JSON держится на трёх вещах: рабочая связь с кассой, валидный JSON по схеме именно вашего драйвера и сходящиеся суммы. Проверяйте их в этом порядке — так вы найдёте причину сбоя быстрее всего.
Проверка результата и работа с ответом драйвера
После отправки задания не ограничивайтесь фактом печати — убедитесь, что чек корректно закрыт на фискальном уровне. В ответе драйвера или в файле результата ищите подтверждение успешного выполнения: номер фискального документа, фискальный признак, отсутствие кода ошибки. Если задание зависло в статусе «выполняется», проверьте ленту в кассе и состояние соединения.
При систематических сбоях включите логирование в драйвере, если такая функция предусмотрена. Лог покажет, на каком поле или команде обрывается обработка, и сэкономит часы на угадывании причины. Никогда не гадайте по симптомам, когда можно прочитать точный код ошибки в ответе драйвера или в его журнале.
Часто задаваемые вопросы
Подойдёт ли один и тот же JSON для касс разных производителей?
Нет. Формат задания определяется драйвером конкретного производителя: названия полей, обязательные параметры и структура различаются. Всегда берите схему из официальной документации на ваш драйвер и вашу его версию.
Как проверить JSON на ошибки перед отправкой на кассу?
Используйте любой онлайн-валидатор JSON или встроенную проверку в редакторе кода — это отловит синтаксические ошибки. Соответствие схеме драйвера придётся сверять вручную по документации, либо тестовой отправкой в режиме эмуляции.
Касса молчит, хотя задание принято. Что делать?
Проверьте, открыта ли смена, есть ли чековая лента и не зависло ли задание в очереди драйвера. Запросите статус задания по его идентификатору — ответ обычно содержит код ошибки или подтверждение выполнения.
Можно ли отладить JSON без реальной кассы?
Часто да: многие драйверы имеют режим эмуляции или тестового устройства, в котором задание обрабатывается без фискализации. Наличие такого режима уточните в документации вашей версии драйвера.
Почему в чеке вместо русских букв печатаются непонятные символы?
Наиболее вероятная причина — неверная кодировка файла. Пересохраните JSON в UTF-8 без BOM. Если проблема сохраняется, проверьте настройки кодовой страницы в драйвере ККТ и шаблон чека.