Інтеграція з 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. Тестові облікові дані видаються при реєстрації. У тестовому режимі чеки не передаються до ФНС — можна безпечно налагоджувати структуру запитів.

Терміни