שילוב CloudKassir עם 1C-Bitrix: פיסקאליזציה לפי 54-FZ

שילוב CloudKassir עם 1C-Bitrix

חנות מקוונת על 1C-Bitrix מקבלת תשלומים מקוונים, אך החוק הפדרלי מס' 54-FZ מחייב הנפקת קבלה פיסקלית בעת ביצוע הסדר. שילבנו את שירות הענן CloudKassir — קבלות לא נשלחות. שגיאות אופייניות: מיפוי מע"מ שגוי, שמות מוצרים קטועים, היעדר callback. תיקנו עשרות מקרים כאלה. המהנדסים שלנו עם ניסיון של 10+ שנים בשילוב Bitrix הכינו קוד מוכן לייצור. להלן יישום מוכח של handler תשלומים עם CloudKassir מהקופסה, כולל callback והחזרות חלקיות. על ידי שימוש ב-CloudKassir, אתם חוסכים $300–$1500 בעלויות חומרה ומשלמים רק $0.02–$0.10 לכל קבלה — זה עד פי 50 זול יותר מאשר בעלות על רשם פיסקלי.

CloudKassir הוא שירות פיסקליזציה בענן התואם ל-54-FZ. הוא פועל במודל של OrangeData ו-Atol Online: ציוד בצד השירות, תשלום לכל קבלה (תלוי בהיקף, החל מ-$0.02 לכל קבלה), ללא קופות רושמות פיזיות. ה-API פשוט יותר — הרשאת Basic Auth, ללא תעודות לקוח. אבל נותרו אתגרים: מיפוי שיעורי מע"מ, אסינכרוניות, הרכב פריטים נכון. נפרק כל שלב. קבלו הערכה חינמית של הפרויקט שלכם — צרו קשר.

איך השילוב עובד

CloudKassir API: מבנה

כתובת בסיס: 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,
];

השדה $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, ]; הוא כתובת ה-callback לאחר הפיסקליזציה. CloudKassir ישלח נתוני קבלה: url, fn, fd, קוד QR. זה נוח יותר מאשר בדיקה תקופתית אם יש לכם IP לבן. Callback אינו חובה אך מומלץ מאוד; בלעדיו, יש לבדוק כל כמה שניות, מה שמגביר את עומס השרת.

בניית פריטי קבלה

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 תווים — fpd הוא חובה. השדה 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; } מקבל ערכים: mb_substr, vat, none, vat0, vat10, vat110. מיפוי משיעור המע"מ של Bitrix למחרוזת של 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',
    };
}

Handler של מערכת תשלומים ב-Bitrix

השילוב מיושם כ-handler ב-vat20. המחלקה מרחיבה את vat120.

הקבלה נשלחת במתודת private function getVatTag(?float $vatRate): string { return match(true) { $vatRate === null || $vatRate == 0 => 'none', $vatRate == 0.1 => 'vat10', $vatRate == 0.2 => 'vat20', default => 'none', }; } — לאחר קבלת אישור ממערכת התשלומים (הבנק). לא ביצירת הזמנה, אלא בדיוק לאחר אישור התשלום.

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-FZ: הקבלה חייבת להיווצר ברגע ההסדר.

טיפול בהחזרות ו-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();
}

מאפייני הזמנה /local/php_interface/include/sale_payment/cloudkassir/, \Bitrix\Sale\PaySystem\ServiceHandler, processRequest() נוצרים ידנית בלוח הניהול לפני השקת השילוב. Callback מבטל את הצורך לבדוק את סטטוס הקבלה ידנית. ללא callback, תצטרכו לבדוק כל כמה שניות, מה שיוצר עומס מיותר על השרת. אם לשרת שלכם יש IP לבן, callback הוא האפשרות המועדפת.

איך ליישם החזרות מלאות וחלקיות

בעת החזר תשלום, שלחו קבלה עם 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; } . הרכב הפריטים חייב להתאים לקבלה המקורית. 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(); } עם הכמויות והסכומים בפועל.

// Пример формирования частичного возврата
$receipt['type'] = 'sell_return';
$receipt['receipt']['items'] = $this->buildPartialReturnItems($order, $returnedItemIds);

ודאו ש-CLOUDKASSIR_FN ו-CLOUDKASSIR_FD ממולאים כראוי. CloudKassir אינו מאמת מול הקבלה המקורית — האחריות לנכונות הנתונים מוטלת על הקוד שלכם.

CloudKassir לעומת מערכת מקומית

שילוב CloudKassir שלנו אורך 3–4 ימים, מהיר פי 3 משילוב מקומי אופייני (1–2 שבועות). המהירות הזו היא הסיבה ש-70% מהלקוחות שלנו בוחרים ב-CloudKassir לפרויקטים חדשים.

תשלום מראש והסדרים רב-שלביים

אם החנות מקבלת תשלום מראש (לדוגמה, 50% בהזמנה, 50% במשלוח), יש לשלוח שתי קבלות:

1. בתשלום הראשון: פריטים עם CLOUDKASSIR_FPD (או type: sell_return), סוג items
2. בהסדר הסופי: פריטים עם // Пример формирования частичного возврата $receipt['type'] = 'sell_return'; $receipt['receipt']['items'] = $this->buildPartialReturnItems($order, $returnedItemIds); , סוג payment_method

זוהי דרישה של 54-FZ. CloudKassir תומך בכך, אך Bitrix אינו תומך בכך מהקופסה. הלוגיקה של שתי הקבלות חייבת להיות מיושמת בהתאמה אישית, בהתבסס על סטטוסי הזמנה וסוג התשלום.

CloudKassir מספק סביבת בדיקה: payment_object. פרטי גישה לבדיקה ניתנים בעת ההרשמה. במצב בדיקה, קבלות לא נשלחות לרשות המסים הפדרלית — ניתן לנפות באגים במבני בקשות בבטחה.

לוחות זמנים ועלות

מה כלול בעבודה

• יישום handler תשלומים עם שליחת קבלה
• יצירת מאפייני הזמנה לנתונים פיסקליים (FN, FD, FPD)
• הגדרת callback לאחסון אוטומטי של מאפיינים פיסקליים
• תמיכה בהחזרות חלקיות ותוכניות תשלום מראש
• בדיקות בסביבת הדמו של CloudKassir
• תיעוד תפעולי (PDF) ותמיכה ל-30 יום לאחר המסירה
• גישה למאגר Git הפרטי שלנו עם קוד מתועד
• מפגש הדרכה מקוון (שעה) לצוות שלכם