Интеграция и разработка

API и Web Requests АТОЛ: подключение кассы к своему приложению

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

2 мин чтения Связаться с техподдержкой
Содержание
  1. Какой интерфейс нужен приложению
  2. Надёжная отправка фискального документа
  3. Что обязательно проверить перед запуском
  4. Где брать примеры

Какой интерфейс нужен приложению

ЗадачаЧто проверить
Касса подключена к компьютеру магазинаSDK драйвера, язык приложения, разрядность библиотеки, поддерживаемая ОС.
Обращение через сервис на локальном компьютереКомпонент-посредник, версия его протокола, адрес и права доступа.
Чеки через АТОЛ ОнлайнAPI провайдера, авторизация, группа ККТ, очередь, итоговые статусы.

Название Web Requests само по себе не определяет сервис и формат данных. Найдите документацию именно установленного компонента. Локальное подключение не должно без необходимости становиться доступным из интернета.

Надёжная отправка фискального документа

  1. Проверьте данные до отправки

    Согласуйте суммы позиций и оплат, налоговые реквизиты, тип расчёта и обязательные поля формата. Валидация в приложении не заменяет проверку кассой, но помогает обнаружить ошибки раньше.

  2. Сохраните идентификаторы

    Свяжите заказ, оплату, запрос и результат. При асинхронной обработке храните UUID задания и внешний идентификатор по правилам API.

  3. Получите окончательный результат

    Подтверждение постановки в очередь и завершение фискализации — разные состояния. Предусмотрите повторное получение результата и обработку задержек.

  4. Разберите неопределённый исход

    Если ответ потерян, сначала установите, оформлен ли документ. Не повторяйте продажу только потому, что истёк тайм-аут HTTP-запроса.

Что обязательно проверить перед запуском

  • Повторное уведомление об одной оплате и защита от дублирования.
  • Временная недоступность кассы или провайдера.
  • Открытый документ, закрытая или просроченная смена.
  • Ошибка одного реквизита и корректная передача её оператору.
  • Возврат, частичная оплата и другие реально используемые сценарии.

Журналируйте код, пространство кодов и текст ошибки вместе. Например, код драйвера не равен такому же числу HTTP. О поиске правильной расшифровки — в справочнике ошибок АТОЛ.

Где брать примеры

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

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

Частые вопросы

Нужно ли устанавливать локальный драйвер для облачного API?

Сам по себе обмен с облачным API по сети не требует управления физической кассой через локальную библиотеку. Ориентируйтесь на схему выбранного сервиса.

Как хранить ключи доступа?

На стороне сервера или в предусмотренном защищённом хранилище. Не помещайте секреты в общедоступный JavaScript сайта и открытые журналы.

Документация, по которой сверяли статью
  • АТОЛ Онлайн, руководство по API и справка
  • АТОЛ, руководство или документация производителя