Перейти к содержимому

Быстрый старт

Четыре шага прямой интеграции с API АТОЛ - с ИИ-ассистентом или своими руками. Фискализация, доступы, код, проверка в песочнице.

Вы делаете прямую интеграцию по API: готовый плагин или платежная кнопка не подходят, код пишется на своей стороне. Дальше - четыре шага, которые проходит человек. Техническую работу - чтение контракта, подбор полей, код - можно отдать ИИ-ассистенту или сделать самому по справочникам этого портала. На каждом шаге есть оба маршрута.

Что понадобится

  • Юридическое лицо или ИП, зарегистрированное в РФ.
  • Доступ в личный кабинет АТОЛ Pay - в нем выдается API-токен. Кабинет боевой среды вы заводите сами на lk.atolpay.ru, доступ в тестовую выдают по запросу (шаг 3).
  • Адрес на вашем сайте, куда АТОЛ будет присылать уведомления об оплате (callback). Нужен публично доступный HTTPS-адрес; на время тестов подойдет временный туннель, например ngrok.
  • Если идете с ассистентом - ИИ-клиент с поддержкой MCP: Claude Code, Claude Desktop, Cursor или VS Code. Если пишете код сами, он не нужен: ниже для каждого шага есть ручной маршрут.
  • Если на шаге 2 выберете свою фискализацию - еще и доступ к АТОЛ Онлайн (логин, пароль, код группы ККТ).

Четыре шага

Выберите, как будете работать

Документация одна. Разница - кто ее читает: ассистент через MCP или вы по страницам этого портала.

MCP-сервер отдает ассистенту документацию этого портала и инструменты интеграции. Он работает на нашей стороне - скачивать и запускать ничего не нужно. Для Claude Code достаточно одной команды:

bash
claude mcp add --transport http atol-docs https://pay.atol.ru/mcp

Конфиги для Claude Desktop, Cursor и VS Code - в разделе Интеграция через ИИ. Инструменты документации работают без токенов и настроек: подключили - и ассистент уже отвечает по документации, а не по памяти.

Решите, нужна ли вам своя фискализация

Единственная развилка, которую нужно пройти человеку: от нее зависит, делаете вы одну интеграцию или две. От выбора не уйти ни с ассистентом, ни без него.

Сомневаетесь - откройте сквозные кейсы использования: там сравнение вариантов по восьми критериям и правило выбора. Можно спросить ассистента - он читает ту же страницу.

Выбрали свою фискализацию - учтите, что нужны отдельные доступы к АТОЛ Онлайн (логин, пароль, код группы ККТ) и зарегистрированные на вас кассы. Запросите их сейчас, чтобы не ждать на шаге 4: порядок - в Общем алгоритме взаимодействия.

Получите доступы и соберите интеграцию

Доступы выдает личный кабинет: ни ассистент, ни эта страница их за вас не заведут. Пройдите пункты по порядку, а первый сделайте сразу: доступ в тестовую среду выдается по письменному запросу, а без него нечего будет проверять на шаге 4.

1. Заведите кабинет и запросите тестовый доступ

Кабинет боевой среды lk.atolpay.ru вы создаете сами - понадобятся телефон и email.

Тестовая среда - это отдельный кабинет (croc-sandbox-lk.atolpay.ru) со своими логином и паролем: их предоставляют по запросу на 1@atol.ru. Именно в тестовой среде вы будете проверять интеграцию на шаге 4 - напишите письмо заранее.

2. Пройдите проверку в банке (онбординг)

Эквайринг подключает банк, поэтому нужна его анкета: в разделе Продукты > Интернет-эквайринг заполните анкету выбранного банка. По результатам проверки банк выдает логин/пароль продавца - они автоматически сохраняются в настройках личного кабинета, отдельно вписывать их никуда не нужно.

3. Сгенерируйте API-токен

В разделе Настройки > API Токены сгенерируйте секретный токен - это ключ, которым ваш код (и, если захотите, ассистент) обращается к API. Он передается во всех запросах API в HTTP-заголовке:

http
Authorization: Bearer <access_token>

Есть и альтернатива - подпись запроса заголовками x-secret-id и x-signature, см. Авторизация.

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

4. Настройте заказы и фискализацию

Эти настройки заполняются один раз в кабинете - ни ассистент, ни ваш код их не видят. Сделайте до тестов.

В разделе Настройки > Настройки заказов укажите:

  • обратный URL по умолчанию (returnUrl) - куда покупатель вернется после оплаты;
  • URL для callback-уведомлений о статусах заказов - куда АТОЛ пришлет результат;
  • банк для оплаты картой и СБП, двухстадийный платеж по умолчанию.

В разделе Провайдер чеков загрузите данные для фискализации (включая версию ФФД), если планируете отправлять чеки.

5. Только для варианта Б: доступ к АТОЛ Онлайн

Если на шаге 2 вы выбрали свою фискализацию, понадобится отдельный набор доступов: логин, пароль и код группы (group_code) из личного кабинета АТОЛ Онлайн, плюс зарегистрированные на вас кассы. Учетные данные АТОЛ Pay здесь не подойдут - это разные сервисы с разными кабинетами. Порядок получения - Общий алгоритм взаимодействия.

Доступы есть. Дальше - код.

Опишите задачу ассистенту обычными словами. Чем конкретнее формулировка, тем меньше уточняющих вопросов:

Подключи прием оплаты АТОЛ Pay к моему Express-приложению: одностадийный платеж картой и СБП, обработчик callback-уведомлений, чек из блока receipt.

Не знаете, на чем написан ваш сайт, - это нормально: откройте проект в ассистенте и попросите разобраться самому.

Посмотри мой проект и подключи прием оплаты АТОЛ Pay: карта и СБП, чеки пробивает АТОЛ Pay. В конце скажи, что мне нужно вписать руками и где.

Если на шаге 2 вы выбрали свою фискализацию, назовите вариант прямо:

Делаем вариант Б из сквозных кейсов: АТОЛ Pay без блока receipt, чеки предоплаты и полного расчета отправляем сами через АТОЛ Онлайн v5. Стек - Python/FastAPI.

Ассистент сам возьмет план интеграции под ваш стек (start_integration), готовые рецепты (get_recipe), описания методов и коды ошибок - и напишет код. Больше формулировок - в примерах промптов.

Токен ассистенту давать не обязательно

Чтобы получить код интеграции, токен не нужен - инструменты документации, планов и валидации работают без него. Токен передают MCP-серверу только когда хотят, чтобы ассистент сам делал тестовые вызовы API; денежные операции при этом остаются отключенными. См. учетные данные.

Когда код готов, не переключайтесь на боевую среду сразу - сначала шаг 4.

Проверьте результат в песочнице

Песочница (она же sandbox, тестовая среда) - копия сервиса, где деньги не списываются по-настоящему, а чеки тестового контура АТОЛ Онлайн не уходят в налоговую. Устроена она так же, как боевая, поэтому проверять интеграцию нужно именно здесь.

Убедиться нужно в четырех вещах:

  • платеж регистрируется, и в ответе приходит ссылка на оплату (data.paymentUrls.main);
  • после оплаты покупатель возвращается на ваш returnUrl;
  • на ваш адрес приходит callback-уведомление и статус заказа меняется;
  • если платеж с блоком receipt (вариант А) - приходит callback type: fiscal с receiptId чека.

Вариант Б. Дополнительно отправьте тестовый чек на https://testonline.atol.ru/possystem/v5/{group_code}/sell и прочитайте результат по uuid методом report. Убедитесь, что в ответе есть ФД и ФПД, а ошибочные запросы возвращают коды 30 (некорректный UUID) и 34 (документ еще в очереди).

Тестовые карты и данные обоих контуров - на странице Тестовые данные.

Попросите ассистента создать тестовый платеж и дать ссылку на оплату. Откройте ее и оплатите тестовой картой. Для варианта Б ассистент прочитает результат чека инструментом get_fiscal_report - в ответе должны быть ФД и ФПД.

Полный чек-лист перевода в бой выдаст инструмент get_recipe с темой go-live-checklist.

Переход на боевую среду

Когда все работает, переключайтесь по списку:

  1. Базовый адрес API - тестовый на боевой (см. таблицу ниже) - и токен из боевого кабинета: кабинеты у сред разные.
  2. В боевом кабинете - returnUrl, URL callback и пройденная анкета банка (Продукты > Интернет-эквайринг).
  3. Для варианта Б - адрес online.atol.ru и боевые логин, пароль и код группы АТОЛ Онлайн.
  4. Если ассистент делает вызовы API сам - заголовок X-Atol-Allow-Live: 1, см. учетные данные.

Ассистент соберет тот же список инструментом get_recipe с темой go-live-checklist.

Среды

СредаЛичный кабинетAPI
Тестовая (sandbox)https://croc-sandbox-lk.atolpay.ruhttps://croc-sandbox-api-mobile.atolpay.ru/v1/ecom/
Боевая (production)https://lk.atolpay.ruhttps://new-api-mobile.atolpay.ru/v1/ecom/

Swagger

Актуальное описание методов в формате Swagger UI доступно по адресу https://new-api-mobile.atolpay.ru/v1/ecom/documentation/. Эта же спецификация в формате OpenAPI 3.0 доступна в нашем портале и используется MCP-сервером.

Куда идти дальше

Эти страницы закрывают вопросы, которые всплывают на шагах 3–4, - и у тех, кто пишет код сам, и у тех, кто проверяет ассистента.