API и Web Requests АТОЛ: подключение кассы к своему приложению
У АТОЛ есть разные способы интеграции: локальный драйвер, его сетевые компоненты и API облачного сервиса. Сначала выберите нужную схему — примеры запросов для АТОЛ Онлайн нельзя отправлять в локальную кассу как команды драйвера.
Связаться с техподдержкойСодержание
Какой интерфейс нужен приложению
| Задача | Что проверить |
|---|---|
| Касса подключена к компьютеру магазина | SDK драйвера, язык приложения, разрядность библиотеки, поддерживаемая ОС. |
| Обращение через сервис на локальном компьютере | Компонент-посредник, версия его протокола, адрес и права доступа. |
| Чеки через АТОЛ Онлайн | API провайдера, авторизация, группа ККТ, очередь, итоговые статусы. |
Название Web Requests само по себе не определяет сервис и формат данных. Найдите документацию именно установленного компонента. Локальное подключение не должно без необходимости становиться доступным из интернета.
Надёжная отправка фискального документа
Проверьте данные до отправки
Согласуйте суммы позиций и оплат, налоговые реквизиты, тип расчёта и обязательные поля формата. Валидация в приложении не заменяет проверку кассой, но помогает обнаружить ошибки раньше.
Сохраните идентификаторы
Свяжите заказ, оплату, запрос и результат. При асинхронной обработке храните UUID задания и внешний идентификатор по правилам API.
Получите окончательный результат
Подтверждение постановки в очередь и завершение фискализации — разные состояния. Предусмотрите повторное получение результата и обработку задержек.
Разберите неопределённый исход
Если ответ потерян, сначала установите, оформлен ли документ. Не повторяйте продажу только потому, что истёк тайм-аут HTTP-запроса.
Что обязательно проверить перед запуском
- Повторное уведомление об одной оплате и защита от дублирования.
- Временная недоступность кассы или провайдера.
- Открытый документ, закрытая или просроченная смена.
- Ошибка одного реквизита и корректная передача её оператору.
- Возврат, частичная оплата и другие реально используемые сценарии.
Журналируйте код, пространство кодов и текст ошибки вместе. Например, код драйвера не равен такому же числу HTTP. О поиске правильной расшифровки — в справочнике ошибок АТОЛ.
Где брать примеры
Для локального SDK используйте комплект официального драйвера с примерами и описанием методов. Для облака — документацию АТОЛ Онлайн, доступную для вашей интеграции. Открытое руководство API v5 редакции 2022 года полезно для понимания асинхронной схемы, но перед разработкой нужно сверить действующую спецификацию, поддерживаемые поля и авторизацию.
Поэтому универсального JSON, который корректно оформит любой расчёт на любой кассе, нет. Рабочий пример должен соответствовать конкретной версии интерфейса и хозяйственной операции.
Частые вопросы
Нужно ли устанавливать локальный драйвер для облачного API?
Сам по себе обмен с облачным API по сети не требует управления физической кассой через локальную библиотеку. Ориентируйтесь на схему выбранного сервиса.
Как хранить ключи доступа?
На стороне сервера или в предусмотренном защищённом хранилище. Не помещайте секреты в общедоступный JavaScript сайта и открытые журналы.
Документация, по которой сверяли статью
- АТОЛ Онлайн, руководство по API и справка
- АТОЛ, руководство или документация производителя