Интеграция с АТОЛ Онлайн для 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 раз дешевле собственного парка устройств.
Если у магазина есть пункт самовывоза с приёмом наличных, потребуется физическая ККТ — облачный сервис фискализирует только безналичные онлайн-платежи. Для гибридной схемы (онлайн-оплата + офлайн-выдача с оплатой на месте) мы используем фискальный сервис только для онлайн-чеков, а офлайн-узлы обслуживаем отдельной физической ККТ. Подход подбираем под фактический поток платежей конкретного магазина.
Как АТОЛ вписывается в цепочку
Цепочка при оплате с фискализацией:
- Покупатель оплачивает заказ — платёжный агрегатор (ЮKassa, Тинькофф и др.) проводит транзакцию
- Агрегатор отправляет уведомление в Битрикс об успешной оплате
- Битрикс (или модуль интеграции) формирует запрос на фискализацию чека
- Сервис АТОЛ регистрирует чек на облачной кассе и передаёт его в ОФД за 1–3 секунды
- Покупатель получает электронный чек на email или по SMS
- Фискальные данные (номер чека, ФН, ФП) возвращаются в Битрикс через webhook
Ключевой момент: АТОЛ работает асинхронно. Запрос на создание чека отправляется, но ответ о результате приходит через webhook или при повторном запросе статуса. Игнорирование этого факта — самая частая причина «потерянных» чеков и недовольных клиентов. В наших проектах callback-обработчик идёт всегда с очередью повторов и dead-letter-логом.
Официальный модуль АТОЛ vs кастомная интеграция
АТОЛ предоставляет официальный модуль atol.kkt54 для 1С-Битрикс — устанавливается через Маркетплейс или вручную. Покрывает базовый сценарий и подходит для магазинов с типовой товарной матрицей и одной системой налогообложения.
После установки настраивается в Магазин → Настройки → АТОЛ:
| Параметр | Откуда взять |
|---|---|
| Login | Личный кабинет АТОЛ |
| Password | Там же |
| Group Code | Идентификатор группы касс |
| INN | ИНН организации |
| Payment Address | URL сайта (как зарегистрирован в АТОЛ) |
| Callback URL | https://shop.ru/local/api/atol-callback.php |
В продакшене у нас почти всегда нужны доработки модуля или замена на кастомную интеграцию: раздельный учёт ОСН и УСН, маркированная номенклатура с автоматической подстановкой кодов из «Честного ЗНАКА», сценарий частичной отгрузки, очередь повторов при таймаутах АТОЛ, корректное распределение НДС в чеках с услугами доставки. Под эти задачи мы пишем интеграцию напрямую с 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 от сервиса
Минимальный callback-обработчик на PHP (показать код)
// 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 дня |
| Кастомная интеграция через API АТОЛ | 3–5 дней |
| Обработчик callback + очередь повторов | 1–2 дня |
| Чеки возврата | 1–2 дня |
| Интеграция с «Честным ЗНАКОМ» (для маркированных товаров) | 2–3 дня |
| Тестирование в тестовой среде АТОЛ | 1–2 дня |
Стоимость рассчитывается по объёму задачи и нюансам конкретного магазина — пишите с описанием стека и сценариев фискализации, оценим проект бесплатно за 1–2 дня.