Интеграция с АТОЛ Онлайн для 1С-Битрикс

Интеграция с АТОЛ Онлайн для 1С-Битрикс

Мы интегрируем облачную кассу АТОЛ Онлайн с интернет-магазинами на 1С-Битрикс под ключ. Закрываем требования 54-ФЗ без покупки физической ККТ. Чеки фискализируются через REST API оператора. Передаются в ОФД. Покупатель получает электронный чек на email или SMS. Готовое решение разворачивается за 3–5 дней.

10+ лет в 1С-Битрикс, 40+ выполненных интеграций фискальных сервисов (АТОЛ, Робокасса, OFD.ru, ЮKassa). В практике — магазины одежды, электроники, маркетплейсы FBO и FBS, B2B-каталоги с оборотом от 2 до 200 миллионов рублей в год. Работаем с маркированной номенклатурой «Честного ЗНАКА». Закрываем сложную товарную матрицу, гибридную налоговую схему и кастомные сценарии возвратов. Согласно 54-ФЗ, все онлайн-платежи физлиц должны проходить через фискальный сервис в течение 5 минут с момента оплаты.

Чем облачная касса лучше физической в интернет-магазине

Физическая ККТ на стороне магазина требует закупки оборудования (от 25 тысяч рублей за устройство), регистрации в ФНС, договора с ОФД, обслуживания и замены ФН каждые 13–36 месяцев. Облачное решение снимает эти расходы — оплата идёт за подписку и за количество фискализированных чеков. Для магазина с потоком до 1000 заказов в месяц SaaS-касса обходится в 3–5 раз дешевле собственного парка устройств.

Если у магазина есть пункт самовывоза с приёмом наличных, потребуется физическая ККТ — облачный сервис фискализирует только безналичные онлайн-платежи. Для гибридной схемы (онлайн-оплата + офлайн-выдача с оплатой на месте) мы используем фискальный сервис только для онлайн-чеков, а офлайн-узлы обслуживаем отдельной физической ККТ. Подход подбираем под фактический поток платежей конкретного магазина.

Как АТОЛ вписывается в цепочку

Цепочка при оплате с фискализацией:

1. Покупатель оплачивает заказ — платёжный агрегатор (ЮKassa, Тинькофф и др.) проводит транзакцию
2. Агрегатор отправляет уведомление в Битрикс об успешной оплате
3. Битрикс (или модуль интеграции) формирует запрос на фискализацию чека
4. Сервис АТОЛ регистрирует чек на облачной кассе и передаёт его в ОФД за 1–3 секунды
5. Покупатель получает электронный чек на email или по SMS
6. Фискальные данные (номер чека, ФН, ФП) возвращаются в Битрикс через webhook

Ключевой момент: АТОЛ работает асинхронно. Запрос на создание чека отправляется, но ответ о результате приходит через webhook или при повторном запросе статуса. Игнорирование этого факта — самая частая причина «потерянных» чеков и недовольных клиентов. В наших проектах callback-обработчик идёт всегда с очередью повторов и dead-letter-логом.

Официальный модуль АТОЛ vs кастомная интеграция

АТОЛ предоставляет официальный модуль atol.kkt54 для 1С-Битрикс — устанавливается через Маркетплейс или вручную. Покрывает базовый сценарий и подходит для магазинов с типовой товарной матрицей и одной системой налогообложения.

После установки настраивается в Магазин → Настройки → АТОЛ:

В продакшене у нас почти всегда нужны доработки модуля или замена на кастомную интеграцию: раздельный учёт ОСН и УСН, маркированная номенклатура с автоматической подстановкой кодов из «Честного ЗНАКА», сценарий частичной отгрузки, очередь повторов при таймаутах АТОЛ, корректное распределение НДС в чеках с услугами доставки. Под эти задачи мы пишем интеграцию напрямую с REST API.

Структура запроса на создание чека

// Отправка чека прихода в АТОЛ class AtolClient { private string $token; private const API = 'https://online.atol.ru/possystem/v4/'; public function getToken(): void { $resp = $this->post('getToken', [ 'login' => ATOL_LOGIN, 'pass' => ATOL_PASSWORD, ]); $this->token = $resp['token']; } public function sendReceipt(array $order): array { $items = []; foreach ($order['basket'] as $item) { $items[] = [ 'name' => mb_substr($item['name'], 0, 128), // ограничение АТОЛ 'price' => (float)$item['price'], 'quantity' => (float)$item['quantity'], 'sum' => round($item['price'] * $item['quantity'], 2), 'payment_method'=> 'full_payment', 'payment_object'=> 'commodity', 'vat' => ['type' => 'none'], // или 'vat20', 'vat10' ]; } if ($order['delivery_price'] > 0) { $items[] = [ 'name' => 'Доставка', 'price' => (float)$order['delivery_price'], 'quantity' => 1.0, 'sum' => (float)$order['delivery_price'], 'payment_method' => 'full_payment', 'payment_object' => 'service', 'vat' => ['type' => 'none'], ]; } $payload = [ 'external_id' => 'BX-' . $order['id'] . '-' . time(), 'receipt' => [ 'client' => [ 'email' => $order['buyer_email'], 'phone' => $order['buyer_phone'] ?? null, ], 'company' => [ 'email' => ATOL_COMPANY_EMAIL, 'sno' => 'osn', // система налогообложения: osn|usn_income|usn_income_outcome|envd|esn|patent 'inn' => ATOL_INN, 'payment_address' => ATOL_PAYMENT_ADDRESS, ], 'items' => $items, 'payments' => [ [ 'type' => 1, // 1=электронный, 0=наличные 'sum' => (float)$order['total'], ], ], 'total' => (float)$order['total'], ], 'service' => [ 'callback_url' => ATOL_CALLBACK_URL, ], 'timestamp' => date('d.m.Y H:i:s'), ]; return $this->post(ATOL_GROUP_CODE . '/sell', $payload); } private function post(string $endpoint, array $data): array { $ch = curl_init(self::API . $endpoint); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json; charset=utf-8', 'Token: ' . $this->token, ], ]); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true) ?? []; } } 

Критичные тонкости при реализации

Сумма позиций должна точно совпадать с total — АТОЛ проверяет это на своей стороне. Расхождение в 1 копейку вызывает ошибку. Типичная проблема при округлении: сумма трёх позиций по 33.33 руб. = 99.99, а total = 100.00. У нас в проектах последней позиции присваивается сумма по остатку — алгоритм покрыт unit-тестами.

Наименование позиции — максимум 128 символов. Длинные названия мы обрезаем с сохранением смысла (отбрасываем хвост атрибутов, оставляем категорию + бренд + модель).

Номенклатурный код (поле nomenclature_code) — обязателен для маркированных товаров: одежда, обувь, парфюмерия, молочная продукция, шины, фотоаппараты и другие. Код берётся из «Честного ЗНАКА». Если магазин работает в этих нишах, без интеграции чеки будут отбиваться. У нас этот этап входит в работу по умолчанию для маркируемой номенклатуры.

Асинхронность — ответ POST /sell содержит только uuid задачи. Фактический результат фискализации приходит в callback. Мы храним uuid в служебной таблице atol_receipts и обрабатываем callback с гарантией at-least-once. Ставим повторы при сетевых таймаутах АТОЛ. Алертим менеджера при превышении 3 неудачных попыток.

Обработчик callback от сервиса

// local/api/atol-callback.php $body = json_decode(file_get_contents('php://input'), true); $uuid = $body['uuid'] ?? ''; $status = $body['status'] ?? ''; // 'done' | 'fail' if ($status === 'done') { $fiscalData = $body['payload']['fiscal_receipt_number'] ?? ''; $fnNumber = $body['payload']['fn_number'] ?? ''; $fnDocument = $body['payload']['fiscal_document_number'] ?? ''; // Сохраняем фискальные данные в заказ saveAtolReceiptData($uuid, [ 'fiscal_number' => $fiscalData, 'fn' => $fnNumber, 'fd' => $fnDocument, 'status' => 'done', ]); } elseif ($status === 'fail') { $error = $body['payload']['message'] ?? 'Unknown error'; logAtolError($uuid, $error); // Ставим задачу в очередь на повтор scheduleAtolRetry($uuid); } http_response_code(200); echo 'OK'; 

Чек возврата

При возврате средств в АТОЛ отправляем чек возврата через метод /sell_refund (полный) или /sell_correction (корректировка). Структура идентична исходному чеку, но endpoint другой:

// Чек полного возврата $atol->post(ATOL_GROUP_CODE . '/sell_refund', $payload); // Чек частичного возврата — только возвращаемые позиции // total и items содержат только возвращаемую часть 

Важно: на чек возврата ссылается ИФНС при налоговой проверке. Расхождение между внутренними возвратами в магазине и фискализированными возвратами в ОФД — повод для штрафа от 10 000 рублей за каждый незакрытый возврат. В наших проектах сверка реестра возвратов с АТОЛ идёт ежедневно через cron.

Наш кейс: магазин одежды с 50+ SKU маркированного товара

Один из наших клиентов — интернет-магазин одежды на 1С-Битрикс с потоком ~800 заказов в месяц. Изначально интеграция АТОЛ работала корректно на немаркированной номенклатуре. После расширения ассортимента маркированными товарами начались ошибки. Часть позиций не имела номенклатурного кода из «Честного ЗНАКА». АТОЛ возвращал fail с сообщением об отсутствии обязательного поля.

Наше решение: в инфоблок «Каталог» добавили обязательное поле «Код маркировки» (UF_MARKING_CODE) с валидацией формата DataMatrix. В момент отправки чека идёт проверка наличия кода для маркируемой категории. Если кода нет — заказ переходит в статус «Требует проверки», менеджер вводит код вручную. Параллельно подключили автозагрузку кодов из «Честного ЗНАКА» через REST API оператора и фоновый синк раз в час.

Результат: время обработки части заказов выросло на 5–15 минут. Зато магазин исключил штрафы за нарушение маркировки (50 000 рублей за чек без обязательного кода) и прошёл налоговую сверку без замечаний.

Что входит в работу

В нашем стандартном пакете интеграции АТОЛ для 1С-Битрикс мы передаём:

• Установку и настройку модуля atol.kkt54 или кастомную интеграцию через REST API
• Класс AtolClient с обработкой токена, повторами и логированием в atol.log
• Обработчик callback с очередью повторов и dead-letter-логикой
• Реестр чеков (служебная таблица + админ-страница со статусами done/pending/fail)
• Скрипт ежедневной сверки магазина с ОФД (cron)
• Документацию по эксплуатации и алерты в Telegram/email на менеджера при провалах
• Тестирование в staging-среде АТОЛ перед переключением на production
• Поддержку первого месяца после запуска: фиксим всё что вылезет в проде

Сроки

Стоимость рассчитывается по объёму задачи и нюансам конкретного магазина — пишите с описанием стека и сценариев фискализации, оценим проект бесплатно за 1–2 дня.