Интеграция с CloudKassir для 1С-Битрикс
Магазин на 1С-Битрикс принимает онлайн-оплату, но Федеральный закон №54-ФЗ требует выдавать фискальный чек в момент расчёта. Подключили облачный сервис CloudKassir — чеки не уходят. Типичная ошибка: неверный маппинг НДС, обрезанные названия товаров, отсутствие callback. Мы такие кейсы исправляли десятками. Наши инженеры с 10+ летним опытом интеграции Битрикса подготовили рабочий код. Ниже — проверенная реализация обработчика платежей с CloudKassir под ключ, включая callback и частичные возвраты.
CloudKassir — облачный сервис фискализации по 54-ФЗ. Работает по модели OrangeData и Атол Онлайн: оборудование на стороне сервиса, плата за чек от 3 рублей, без физических касс. API проще — авторизация Basic Auth, нет клиентских сертификатов. Но сложности остаются: маппинг ставок НДС, асинхронность, корректное оформление позиций. Мы разберём каждый этап. Оценим ваш проект бесплатно — пишите.
Как работает интеграция?
API CloudKassir: структура
Базовый URL: https://api.cloudkassir.ru/v1/. Авторизация: Basic Auth, логин и пароль из личного кабинета.
Ключевые методы:
-
POST /receipts— отправить чек -
GET /receipts/{id}— статус обработки чека -
POST /receipts/correction— чек коррекции
Ответ на POST /receipts возвращает id — внутренний идентификатор задачи. Сам чек в ответе не содержится, нужно опрашивать GET /receipts/{id}.
Структура чека
$receipt = [
'external_id' => 'order-' . $orderId . '-' . time(),
'receipt' => [
'client' => [
'email' => $customerEmail, // обязательно email или телефон
],
'company' => [
'email' => $shopEmail,
'sno' => 'osn', // osn, usn_income, usn_income_outcome
'inn' => $inn,
'payment_address' => $siteUrl,
],
'items' => $this->buildItems($payment),
'payments' => [
[
'type' => 2, // 1-наличные, 2-электронные
'sum' => $payment->getSum(),
],
],
'total' => $payment->getSum(),
],
'timestamp' => date('d.m.Y H:i:s'),
'type' => 'sell', // sell, sell_return
'url' => $callbackUrl,
];
Поле url — адрес для callback после фискализации. CloudKassir отправит POST с данными чека: fn, fd, fpd, QR-код. Это удобнее polling, если есть белый IP.
Построение позиций чека
private function buildItems(\Bitrix\Sale\Payment $payment): array
{
$order = $payment->getOrder();
$items = [];
foreach ($order->getBasket() as $basketItem) {
$items[] = [
'name' => mb_substr($basketItem->getField('NAME'), 0, 128),
'price' => $basketItem->getPrice(),
'quantity' => $basketItem->getQuantity(),
'sum' => $basketItem->getFinalPrice(),
'payment_method' => 'full_payment', // предоплата / полный расчёт
'payment_object' => 'commodity', // товар, услуга, работа
'vat' => $this->getVatTag($basketItem->getField('VAT_RATE')),
];
}
if ($order->getDeliveryPrice() > 0) {
$items[] = [
'name' => 'Доставка',
'price' => $order->getDeliveryPrice(),
'quantity' => 1.0,
'sum' => $order->getDeliveryPrice(),
'payment_method' => 'full_payment',
'payment_object' => 'service',
'vat' => 'none',
];
}
return $items;
}
Длина наименования ограничена 128 символами — mb_substr обязателен. Поле vat принимает значения: none, vat0, vat10, vat110, vat20, vat120. Маппинг из ставки НДС Битрикс в строку CloudKassir:
private function getVatTag(?float $vatRate): string
{
return match(true) {
$vatRate === null || $vatRate == 0 => 'none',
$vatRate == 0.1 => 'vat10',
$vatRate == 0.2 => 'vat20',
default => 'none',
};
}
Обработчик платёжной системы в Битрикс
Интеграция реализуется как обработчик в /local/php_interface/include/sale_payment/cloudkassir/. Класс наследует \Bitrix\Sale\PaySystem\ServiceHandler.
Чек отправляется в методе processRequest() — после получения подтверждения от платёжной системы (банка). Не при создании заказа, а именно после подтверждения факта оплаты.
public function processRequest(
\Bitrix\Sale\Payment $payment,
\Bitrix\Main\Request $request
): \Bitrix\Sale\PaySystem\ServiceResult {
$result = new \Bitrix\Sale\PaySystem\ServiceResult();
// Сначала помечаем платёж как оплаченный
$result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING);
// Затем отправляем чек
$this->sendReceipt($payment);
return $result;
}
Если чек отправить до подтверждения оплаты — нарушение 54-ФЗ: чек должен быть сформирован в момент расчёта.
Обработка возвратов и callback
Почему важен callback и как сохранить фискальные данные?
При поступлении callback от CloudKassir (после успешной фискализации) сохраняем данные в свойства заказа:
public function handleCallback(array $callbackData): void
{
$orderId = $this->extractOrderId($callbackData['external_id']);
$order = \Bitrix\Sale\Order::load($orderId);
$propCollection = $order->getPropertyCollection();
$propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FN')
->setValue($callbackData['fn']);
$propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FD')
->setValue($callbackData['fd']);
$propCollection->getItemByOrderPropertyCode('CLOUDKASSIR_FPD')
->setValue($callbackData['fpd']);
$order->save();
}
Свойства заказа CLOUDKASSIR_FN, CLOUDKASSIR_FD, CLOUDKASSIR_FPD создаются вручную в административной части перед запуском интеграции. Callback избавляет от необходимости опрашивать статус чека вручную. Без callback придётся крутить polling каждые несколько секунд, что создаёт лишнюю нагрузку на сервер. Если ваш сервер имеет белый IP, callback — предпочтительный вариант.
Как реализовать полные и частичные возвраты?
При возврате оплаты отправляется чек с type: sell_return. Состав позиций должен совпадать с оригинальным чеком. CloudKassir не связывает чеки по ID автоматически — правильность состава на стороне вашего кода.
Для частичных возвратов (только часть товаров) — в items передаются только возвращаемые позиции с их фактическими количеством и суммами.
// Пример формирования частичного возврата
$receipt['type'] = 'sell_return';
$receipt['receipt']['items'] = $this->buildPartialReturnItems($order, $returnedItemIds);
Убедитесь, что payment_method и payment_object заполнены корректно. CloudKassir не выполняет сверку с оригинальным чеком — ответственность за корректность данных лежит на вашем коде.
CloudKassir против on-premise
| Параметр | CloudKassir | On-premise касса |
|---|---|---|
| Оборудование | Не требуется | Фискальный регистратор |
| Обслуживание | Плата за чек (от 3 руб.) | Обслуживание кассы |
| Интеграция | API, 3–4 дня | 1–2 недели |
| Мобильность | Любой интернет | Привязка к месту |
Предоплата и расчёты в несколько этапов
Если магазин принимает предоплату (например, 50% при заказе, 50% при доставке), нужно отправлять два чека:
- При первом платеже: позиции с
payment_method: prepayment(илиadvance), типsell - При закрытии расчёта: позиции с
payment_method: full_payment, типsell
Это требование 54-ФЗ. CloudKassir его поддерживает, Битрикс из коробки — нет. Логику двух чеков нужно реализовывать кастомно, ориентируясь на статусы заказа и тип платежа.
CloudKassir предоставляет тестовый стенд: https://demo.cloudkassir.ru. Тестовые учётные данные выдаются при регистрации. В тестовом режиме чеки не передаются в ФНС — можно безопасно отлаживать структуру запросов.
Сроки и стоимость
| Состав | Срок |
|---|---|
| Приход + возврат, Basic Auth | 3–4 дня |
| + Callback обработчик + сохранение ФД | +1 день |
| + Предоплатная схема (два чека) | +2 дня |
Что входит в работу
- Реализация обработчика платежей с отправкой чеков
- Создание свойств заказа для фискальных данных (ФН, ФД, ФПД)
- Настройка callback для автоматического сохранения фискальных признаков
- Реализация поддержки частичных возвратов и предоплатных схем
- Тестирование на demo-стенде CloudKassir
- Документация по эксплуатации и поддержка 30 дней после сдачи
Чек-лист запуска интеграции
- Зарегистрироваться в CloudKassir, получить логин/пароль.
- Создать свойства заказа
CLOUDKASSIR_FN,CLOUDKASSIR_FD,CLOUDKASSIR_FPD. - Разместить обработчик в
/local/php_interface/include/sale_payment/cloudkassir/. - Настроить callback URL (если есть белый IP).
- Проверить маппинг ставок НДС.
- Выполнить тестовую оплату на demo-стенде.
- Проверить сохранение фискальных данных в свойствах заказа.
- Если есть предоплата — реализовать два чека.
- Запустить на боевом стенде и проконтролировать первые чеки.
- Передать документацию заказчику.
Более 80 проектов по фискализации, 10+ лет опыта с Битрикс. Мы сопровождаем интеграцию на всех этапах. Получите консультацию по вашей задаче — оценим проект в течение дня.