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

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

10+ років в 1С-Бітрікс, 40+ виконаних інтеграцій фіскальних сервісів (АТОЛ, Робокасса, OFD.ru, ЮKassa). Понад 5 років на ринку фіскальних послуг. У практиці — магазини одягу, електроніки, маркетплейси 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-логом.

Що обрати: офіційний модуль чи кастомна інтеграція?

АТОЛ надає офіційний модуль 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 дні. Наприклад, базова інтеграція коштує від 5 000 грн, з кастомними доробками — від 15 000 грн.