Чек-лист интеграции

Что проверить перед выпуском: требования к клиенту и минимальный план испытаний на демо-кассе.

Клиент

• id это GUID, создаётся один раз на заказ и не меняется при повторах.
• Статус опрашивается раз в 1–2 секунды, общий таймаут 3–5 минут.
• PROCESSING обрабатывается как «ждём», а не как ошибка.
• Таймаут опроса не приводит к автоматическому повтору с новым id.
• Суммы считаются в decimal. Для смешанной оплаты проверено cash_sum + cashless_sum == Σ price × quantity.
• Токен обмена хранится в настройках и легко меняется.
• Перед повтором с новым id выполняется поиск по старому.
• Сохраняются kkmID, qr, fdNumber, shiftNumber.
• Есть индикатор доступности кассы: check-token для HTTP, запрос статуса для TCP.

Только TCP

• Одно соединение на один запрос, чтение по Content-Length.
• Разбираются оба формата ошибок: fail/message и ERROR/info.
• Порт кассы закрыт от гостевой сети и интернета, IP закреплён.

Если используете

• Блок print в документе: значения помещаются по ширине чека, реквизиты совпадают с регистрацией.
• Блок print в ответе: запрошен needPrint: true, предусмотрен случай, когда блока нет.
• Обмен валюты: курс и сумма передаются в price и quantity, валюта пополняется через /gate/cash, отказ по балансу обрабатывается как обычный отказ.
• Возвраты по безналу: rrn каждой продажи картой сохраняется и уходит в возврат, для продаж без банка передаётся skip_bank: true.

План испытаний

Проверьте на демо-контуре. Для каждого случая сохраните входной JSON, id, последовательность статусов и итоговые реквизиты.

1. Доступность HTTP и TCP.
2. Наличная продажа, статус OK.
3. Безналичная продажа на терминале: успех, отмена, отказ банка.
4. Повтор того же id после искусственного таймаута.
5. Смешанная оплата и проверка равенства сумм.
6. Возврат по верному и по неизвестному fd_number, возврат на карту.
7. Перезапуск приложения кассы между приёмом и статусом.
8. Закрытая смена, открытие смены, закрытие после незавершённого документа.
9. Неверный токен, недоступный порт, приложение в фоне.
10. Два документа подряд и обрыв связи после отправки.

Рекомендуемая структура кода

Удобно сделать один интерфейс, а транспорт оставить сменным:

YaKassaClient
  submitReceipt(document) → Accepted(id)
  getReceiptStatus(id)    → ReceiptResult
  openShift() / closeShift()

Модели документа и обработчик статусов общие, транспорт HTTP или TCP подставляется. Очередь исходящих операций, защита от дублей по id, паузы между попытками и восстановление после перезапуска живут выше транспорта. Незавершённые id держите в постоянном хранилище: при запуске программы они должны восстанавливаться. Тогда переход с TCP на HTTP не меняет логику продажи.