M cenaly.ru
🔌 Кассовый сервер: чеки по API

🧾 Кассовый сервер: чеки 54-ФЗ по API

Фискализация интернет-продаж на собственной ККТ: как работает, что нужно для подключения и чем отличается от аренды кассы в дата-центре

Документация

Кассовый сервер: чеки 54-ФЗ по API на своей кассе

Кассовый сервер — это фискализация интернет-продаж без аренды кассы в дата-центре. Ваш сайт, CRM или учётная система отправляет чек обычным HTTP-запросом, а документ пробивается на вашей собственной ККТ, которая уже стоит в магазине, офисе или на складе.

Протокол намеренно совместим с АТОЛ Онлайн v5 (ФФД 1.2) и v4 (ФФД 1.05): если ваш модуль или SDK уже умеет говорить с АТОЛ Онлайн, интеграция сводится к смене базового URL и реквизитов доступа.

1. Как это работает#

ваш сервер ──HTTP──► 54fz.cenaly.ru ──очередь──► Cenaly Hardware Bridge ──► ваша ККТ ──► ОФД → ФНС
     ▲                     │                     (кассовый ПК магазина)
     └───callback + report─┘
  1. Ваш бэкенд получает оплату и отправляет JSON-чек на POST /possystem/v5/{group_code}/sell.
  2. Сервис отвечает мгновенно: {"uuid": "...", "status": "wait"} — документ принят в очередь.
  3. Очередь выбирает свободную кассу вашей группы и отправляет задание мосту на кассовом ПК.
  4. Касса пробивает чек, ОФД отправляет электронный чек покупателю на e-mail или телефон.
  5. Вы получаете результат: POST на ваш callback_url и/или GET .../report/{uuid} — с номером ФД, фискальным признаком, номером ФН и РН ККТ.

Типичное время от запроса до done — несколько секунд. Предельное время ожидания свободной кассы — 300 секунд, после чего документ получает статус fail с типом timeout.

2. Чем это отличается от облачной кассы в аренду#

Аренда ККТ в дата-центре Кассовый сервер
Где физически стоит касса В дата-центре провайдера У вас: магазин, офис, склад
Кто владелец ККТ и ФН Вы (аппарат арендован) Вы (аппарат уже ваш)
Ежемесячная плата за железо Есть, обычно основная часть счёта Нет — касса у вас уже есть
Кто отправляет чек в ОФД Касса провайдера Ваша касса
Бумажный чек Не печатается Не печатается (интернет-расчёт — электронный чек)
Та же касса обслуживает зал Нет, это отдельный аппарат Да — одна ККТ на офлайн-точку и сайт

Одна ККТ законна и для торгового зала, и для сайта: см. Облачная касса и Чеки интернет-магазина. Мы предоставляем транспорт и очередь до вашей кассы — оператором фискальных данных мы не являемся, чек формируется вашей ККТ от вашего имени и на ваш ИНН.

3. Что нужно для подключения#

1. Собственная ККТ, зарегистрированная для интернет-расчётов. В карточке регистрации должен стоять признак «расчёты в Интернете», а в месте расчётов (тег 1187) — адрес вашего сайта. Если касса зарегистрирована только на розничный адрес, нужна перерегистрация — мастер регистрации есть в самом мосте.

2. Кассовый ПК с установленным Cenaly Hardware Bridge. Мост — фоновая служба Windows или Linux, которая держит связь с кассой и облаком. Установка — обычный инсталлятор, автозапуск настраивается сам; см. Cenaly Hardware Bridge.

3. Постоянный интернет и включённый кассовый ПК. Чек пробивается на вашем оборудовании: если ПК выключен, документ ждёт в очереди и через 300 секунд возвращает ошибку. Для ночных заказов держите кассовый ПК включённым.

4. Расширение «API кассы (Россия)». Раздел включается карточкой «API кассы (Россия)» в «Магазине приложений». Расширение платное: 790 ₽ в месяц или 7900 ₽ в год за каждую подключённую кассу, и доступно только локациям в России.

5. Свой кассовый сервер. Реквизиты доступа вы создаёте сами: раздел админки «API кассы» → кнопка «Создать кассовый сервер». Мастер из двух шагов — выбор кассы из вашего реестра оборудования (можно добавить и резервную) и реквизиты компании (название, ИНН, система налогообложения по умолчанию, версия протокола). На последнем шаге выдаются group_code, логин и пароль. Пароль показывается один раз и хранится только хешем: потерянный пароль не восстанавливается, его можно лишь сменить кнопкой «Сменить пароль» (уже выданные токены доживут свои 24 часа).

В мастере есть флажок «Тестовый режим»: документы принимаются и проверяются, но на кассу не уходят — удобно отладить интеграцию до первого боевого чека. Режим переключается и потом: кнопка «Настройки» в строке сервера открывает правку названия и тестового режима, так что отлаженный сервер переводится в боевой без пересоздания и без смены реквизитов. Есть и общая тестовая группа на mock-кассе — её реквизиты выдаёт поддержка.

Совместимость касс#

Электронный чек без печати сегодня уверенно поддерживают кассы АТОЛ (драйвер ДТО-10). Для остальных семейств (ШТРИХ-М, Пирит, Меркурий) мост используется в офлайн-сценариях — интернет-чек без печати они либо не поддерживают, либо не заявляют поддержку в протоколе. Перед подключением проверьте свою модель у поддержки: несовместимость видна на этапе настройки, а не на первом боевом чеке.

4. Порядок подключения#

Шаг Что делаете Результат
1 Проверяете карточку регистрации ККТ (признак «расчёты в Интернете», тег 1187 = адрес сайта) Касса юридически пригодна для интернет-чеков
2 Ставите мост на кассовый ПК и привязываете его к аккаунту Касса видна в облаке
3 Включаете расширение «API кассы (Россия)» в «Магазине приложений» В админке появляется раздел «API кассы»
4 «API кассы» → «Создать кассовый сервер»: выбираете кассу и заполняете реквизиты Получаете group_code, логин и пароль (пароль — один раз)
5 Интегрируете API: getToken → sell → report Тестовый чек проходит
6 Заводите боевой сервер (без «Тестового режима») и подписываетесь на callback_url Чеки бьются автоматически

Готовность интеграции определяется просто: первый report со статусом done и заполненным fiscal_document_number.

5. Что сервис умеет и чего не умеет сегодня#

Умеет:

  • 8 операций протокола: sell, sell_refund, buy, buy_refund и четыре вида чеков коррекции;
  • полный состав чека ФФД 1.2: покупатель (в т.ч. расширенные реквизиты), СНО, признаки способа и предмета расчёта, единицы измерения, ставки НДС (включая 5 %, 7 %, 22 %), агентские реквизиты, отраслевые и операционные реквизиты;
  • идемпотентность по external_id — повторный запрос никогда не пробивает второй документ;
  • очередь с балансировкой по нескольким кассам группы, включая резервные;
  • доставку результата callback'ом с повторами и поллингом.

Пока не умеет (честно):

  • Проверку кода маркировки в «Честном знаке» / ТС ПИоТ — код маркировки передаётся в кассу как есть, разрешительный режим на нашей стороне не реализован;
  • ссылку на чек в ОФД (ofd_receipt_url) — поле возвращается пустым: кассовые драйверы её не отдают, чек ищется в личном кабинете вашего ОФД по номеру ФД;
  • отдельный публичный API мониторинга ККТ (статус ФН, непереданные документы) — в разработке. Само состояние касс видно в разделе «API кассы»: связь каждой кассы (на связи / нет связи / убрана из оборудования), очередь (сколько документов ждёт и сколько в работе), пробито и отказов за сутки, последний чек и последний отказ, а рядом — журнал чеков с фискальными реквизитами.

Сервис доступен только в российском контуре бренда cenaly.ru: весь путь чека и персональные данные покупателей остаются в российской инфраструктуре.

6. Дальше#

Документация
Демо меню гостя Демо админ-панели Начать бесплатно