ККТ АТОЛ для разработчиков: драйвер, API, тестирование и WebRequests

Где находится драйвер в вашей системе

Кассовое приложение задаёт содержание операции, а ДККТ обеспечивает взаимодействие с кассой. Фискализация выполняется в ККТ и её накопителе. Ответ программы о постановке задачи, успешный обмен по интерфейсу и созданный фискальный документ не являются одним результатом.

Сначала зафиксируйте расположение компонентов: приложение на кассовом компьютере, удалённый сервер, локальный сервис и подключённая ККТ. Определите, кто владеет соединением и выполняет команды. Для одной кассы важно согласовать последовательность обращений, чтобы диагностика, продажа и дополнительные сервисы не воспринимались приложением как независимые, одновременно доступные операции.

Библиотека, JSON или WebRequests: что выбрать

WebRequests и АТОЛ Онлайн относятся к разным схемам. Первый компонент работает в составе решения на базе драйвера, а облачная фискализация использует собственный протокол сервиса. Учетные данные, адреса и жизненный цикл запроса из одной схемы нельзя переносить в другую по сходству слова API.

Как подготовить SDK и зависимости

Подберите дистрибутив для ОС и архитектуры процесса. ДККТ предоставляет C-API и интеграционные компоненты для ряда языков, включая Python, Java, C# и C++. Подключение обёртки не отменяет необходимость совместимой нативной библиотеки и её зависимостей. В среде с несколькими копиями SDK фиксируйте путь фактической загрузки.

Для Python используется модуль libfptr10.py; ему можно передать путь к библиотеке. Если путь не задан, предусмотрен поиск в каталогах установки и системы. Поэтому различия между запуском из среды разработки и рабочего приложения могут объясняться окружением. Сохраняйте версию библиотеки и используемой обёртки вместе с конфигурацией проекта.

Как различать локальный и серверный доступ

Прямое подключение к библиотеке, WebRequests и сервер удалённого подключения — разные способы построения интеграции. Сначала выберите один предусмотренный путь и определите, какой процесс владеет соединением с кассой. Не открывайте один физический порт одновременно из нескольких тестовых и рабочих приложений.

Для удалённого варианта отдельно проверяют доступность серверного компонента и его соединение с ККТ. Успешный запрос к сетевому сервису ещё не подтверждает ответ оборудования. В журнале нужно различать ошибку клиентского запроса, недоступность сервера и ответ самой кассы.

Как проверить подключение без продажи

1. Подготовьте питание, интерфейс и параметры нужной ККТ.
2. Создайте экземпляр драйвера средствами выбранной интеграции.
3. Примените параметры соединения и откройте подключение.
4. Запросите модель, заводской номер и версию внутреннего ПО.
5. Прочитайте состояние смены, ФН и открытого документа.
6. Сохраните полученные сведения и результат каждого вызова.

Такая последовательность проверяет доступ к оборудованию без регистрации вымышленной продажи. Если необходимо автоматическое определение модели, используйте предусмотренную SDK настройку, а не случайную подстановку соседней модели. Идентификатор из тестового проекта должен соответствовать фактическому устройству и поддерживаемому способу подключения.

Как проверять и выполнять JSON-задание

Тип задания задаётся полем type, а остальные поля должны соответствовать выбранной операции. Для предварительной проверки в ДККТ предусмотрен validateJson(), для выполнения — processJson(). Текст передаётся в LIBFPTR_PARAM_JSON_DATA. Результат выполнения читается из соответствующего параметра, если операция завершилась без ошибки.

Проверку формата можно выполнять отдельно от подключения к ККТ. Но её успешное завершение не доказывает допустимость операции при текущем состоянии смены, ФН и лицензий. Если набор скриптов не содержит требуемой проверки, драйвер возвращает отдельную ошибку отсутствующей функции валидации. Это отличается от доказанного соответствия задания всем требованиям.

При использовании собственных обработчиков фиксируйте их версии вместе с библиотекой драйвера. Изменённый внешний скрипт может переопределять штатное поведение. Поэтому одинаковый номер основной библиотеки ещё не гарантирует одинаковый результат двух установок с разными скриптами.

Что нужно для WebRequests

WebRequests устанавливается как отдельный компонент Windows-дистрибутива и не входит в безусловно устанавливаемый минимум. Сначала подтвердите его наличие и запуск, затем параметры сервиса и настройку оборудования. Установка только нативной библиотеки не поднимает этот уровень интеграции автоматически.

Адрес, порт, способ обращения и формат ответа берите из комплекта документации своей версии. Не используйте URL и токены облачного сервиса вместо настроек локального компонента. При ошибке разделяйте недоступность самого сервиса, отсутствие соединения с ККТ и отказ конкретной команды. Доступный HTTP-сервис ещё не подтверждает готовность накопителя к продаже.

Эмулятор, проверка JSON и реальная ККТ

Для каждого этапа определите, что именно проверяет тестовая среда. Проверка структуры задания полезна для поиска ошибок формата. Она не воспроизводит состояние физического ФН, печатающего механизма и канала передачи документов. Если для выбранного SDK не предусмотрен нужный эмулятор, аппаратные операции проверяют на совместимом оборудовании в согласованном сценарии.

Тест драйвера является инструментом управления устройством, а не гарантированно нефискальным симулятором. Команда регистрации, закрытия архива или продажи может изменить реальное состояние ККТ. Разделите набор проверок на чтение параметров, предварительную валидацию и операции с фискальным результатом. Для последних заранее определяют данные и порядок контроля.

Как обрабатывать результат чека и повтор запроса

После закрытия документа проверяйте его фактический статус. Метод checkDocumentClosed() позволяет различать завершение документа и печати. При потере связи или бумаги документ может уже находиться в ФН. Повторная отправка исходной продажи до проверки статуса способна создать второй расчёт вместо восстановления печати.

Сохраняйте номер ФН, номер ФД, фискальный признак и время документа вместе с идентификатором операции вашей системы. Отдельно учитывайте подтверждение обмена с ОФД. Состояния «задание отправлено», «документ закрыт», «чек напечатан» и «получена квитанция» должны иметь понятное значение в журнале и интерфейсе приложения.

Какие сведения журналировать при интеграции

Для каждого сбоя сохраняйте название метода, тип задания, код и текст ответа, состояние кассы и время. В ДККТ предусмотрены разные категории логирования, включая высокоуровневые вызовы, транспорт, USB, COM и Web. Выбирайте журнал, относящийся к проблемному уровню, и согласованный интервал воспроизведения.

При обновлении повторите использованные сценарии на той же модели и ФФД. В перечень проверки включают обычные расчёты, возвраты, коррекции, маркировку и восстановление после обрыва, если они предусмотрены решением. SDK и руководства доступны в официальном центре загрузок АТОЛ. Для обращения подготовьте минимальный воспроизводимый сценарий и версии всех участвующих компонентов.