Интеграция с CloudKassir для 1С-Битрикс

Интеграция с CloudKassir для 1С-Битрикс

CloudKassir — облачный сервис фискализации чеков по 54-ФЗ. Работает по той же модели, что OrangeData и Атол Онлайн: оборудование на стороне сервиса, вы платите за каждый пробитый чек и не думаете об обслуживании физических касс. API у CloudKassir проще, чем у конкурентов — авторизация через логин/пароль с Basic Auth, нет требования клиентских сертификатов. Это снижает порог входа, но не убирает основные сложности: маппинг ставок НДС, асинхронность, корректное оформление позиций по 54-ФЗ.

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 от 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 создаются вручную в административной части перед запуском интеграции.

Возвраты: тип sell_return

При возврате оплаты отправляется чек с type: sell_return. Состав позиций должен совпадать с оригинальным чеком. CloudKassir не связывает чеки по ID автоматически — правильность состава на стороне вашего кода.

Для частичных возвратов (только часть товаров) — в items передаются только возвращаемые позиции с их фактическими количеством и суммами.

Особенности при работе с предоплатами

Если магазин принимает предоплату (50% при заказе, 50% при доставке), нужно отправлять два чека:

1. При первом платеже: позиции с payment_method: prepayment (или advance), тип sell
2. При закрытии расчёта: позиции с payment_method: full_payment, тип sell

Это требование 54-ФЗ. CloudKassir его поддерживает, Битрикс из коробки — нет. Логику двух чеков нужно реализовывать кастомно, ориентируясь на статусы заказа и тип платежа.

Тестирование

CloudKassir предоставляет тестовый стенд: https://demo.cloudkassir.ru. Тестовые учётные данные выдаются при регистрации. В тестовом режиме чеки не передаются в ФНС — можно безопасно отлаживать структуру запросов.

Сроки