שילוב החזרים חלקיים ב-1C-Bitrix: APIs וקבלות פיסקליות

שילוב החזרים חלקיים ב-1C-Bitrix: APIs וקבלות פיסקליות

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

למה החזר חלקי הוא משימה לא טריוויאלית עבור Bitrix

מודולי Bitrix סטנדרטיים תומכים לעיתים קרובות רק בהחזרים מלאים. לפי תיעוד 1C-Bitrix על מודול המכירות, החזרים חלקיים דורשים פיתוח מותאם אישית: אינטגרציה עם APIs של מערכות תשלום, יצירת קבלת החזר לפי 54-FZ, ועדכון סטטוסים במודול המכירות. ללא יישום איכותי, עלולים להיווצר פערים בין סכום ההחזר לקבלה, מה שמוביל לחסימת הקופה הרושמת על ידי רשויות המס. ב-95% מהמקרים, השגיאה נובעת מחוסר התאמה בין סכום ההחזר לסכום הקבלה. החזרים חלקיים מהווים כ-20% מכלל בקשות ההחזר במסחר אלקטרוני.

היכן מבוצע החזר חלקי

החזר חלקי יזום על ידי החנות דרך ה-API של מערכת התשלום. הקונה פונה לתמיכה, והמנהל מעבד את ההחזר בלוח הניהול של Bitrix — או דרך הממשק הסטנדרטי (אם המודול תומך בכך) או דרך handler מותאם אישית. אנו מיישמים ממשק נוח למנהל עם בחירת פריטים ויצירת בקשה אוטומטית. לדוגמה, החזר חלקי לאחרונה לחנות בגדים היה סכום חלקי עבור חולצה שהוחזרה.

איך להבטיח שקבלת ההחזר נכונה?

נקודת המפתח היא שסך הפריטים בקבלה חייב להתאים בדיוק לסכום ההחזר. אפילו פער של אגורה יגרום לשגיאת OFD. אנו משתמשים באימות אוטומטי לפני השליחה: משווים את הסכום הסופי לסכום המבוקש; אם הם לא תואמים, אנו חוסמים את השליחה ומציגים אזהרה. זה מבטל קנסות. בנוסף, אנו מיישמים רישום (logging) של כל הבקשות לצורך ביקורת.

דוגמאות ל-API של החזרים

Tinkoff:

$params = [
    'TerminalKey' => TINKOFF_TERMINAL,
    'PaymentId' => $externalPaymentId, // ID платежа в Тинькофф
    'Amount' => (int)($refundAmount * 100), // копейки
];
$params['Token'] = tinkoffSign($params, TINKOFF_SECRET);
$result = tinkoffPost('/v2/Cancel', $params);
// result['Status'] === 'REFUNDED' — успешный возврат

YooKassa:

use YooKassa\Client;

$client = new Client();
$client->setAuth($shopId, $secretKey);

$refund = $client->createRefund([
    'payment_id' => $externalPaymentId,
    'amount' => [
        'value' => number_format($refundAmount, 2, '.', ''),
        'currency' => 'USD',
    ],
    'description' => 'Возврат позиции: ' . $itemName,
    'receipt' => $refundReceiptData, // обязателен при подключённой кассе
], uniqid('', true));

קבלת החזר (54-FZ)

אם קופה רושמת מקוונת מחוברת, החזר חלקי דורש שליחת קבלת החזר ל-OFD. המבנה של קבלת ההחזר זהה למקורית, אבל:

• מסמך $params = [ 'TerminalKey' => TINKOFF_TERMINAL, 'PaymentId' => $externalPaymentId, // ID платежа в Тинькофф 'Amount' => (int)($refundAmount * 100), // копейки ]; $params['Token'] = tinkoffSign($params, TINKOFF_SECRET); $result = tinkoffPost('/v2/Cancel', $params); // result['Status'] === 'REFUNDED' — успешный возврат : use YooKassa\Client; $client = new Client(); $client->setAuth($shopId, $secretKey); $refund = $client->createRefund([ 'payment_id' => $externalPaymentId, 'amount' => [ 'value' => number_format($refundAmount, 2, '.', ''), 'currency' => 'USD', ], 'description' => 'Возврат позиции: ' . $itemName, 'receipt' => $refundReceiptData, // обязателен при подключённой кассе ], uniqid('', true)); (ב-ATOL), type (ב-YooKassa)
• הקבלה כוללת רק את הפריטים המוחזרים עם הסכומים המוחזרים
• סך הפריטים בקבלה חייב להתאים בדיוק לסכום ההחזר

// Пример чека возврата для ЮКасса
$refundReceiptData = [
    'customer' => ['email' => $buyer->getEmail()],
    'items' => [],
];

foreach ($refundItems as $item) {
    $refundReceiptData['items'][] = [
        'description' => $item['name'],
        'quantity' => $item['quantity'],
        'amount' => [
            'value' => number_format($item['price'] * $item['quantity'], 2, '.', ''),
            'currency' => 'USD',
        ],
        'vat_code' => $item['vat_code'],
        'payment_subject' => 'commodity',
        'payment_mode' => 'full_payment',
    ];
}

// Проверяем: сумма позиций === сумма возврата
$itemsTotal = array_sum(array_column(
    array_map(fn($i) => ['sum' => $i['price'] * $i['quantity']], $refundItems),
    'sum'
));

assert(abs($itemsTotal - $refundAmount) < 0.01, 'Расхождение суммы чека!');

עדכון סטטוסים ב-Bitrix

לאחר החזר מוצלח, יש לעדכן את המצב במודול המכירות:

// Частичный возврат — не ставим оплату как "возвращена" полностью
// Только записываем сумму возврата и обновляем статус товарной позиции
$payment = $order->getPaymentCollection()->getItemById($paymentId);
$payment->setField('PS_STATUS_MESSAGE', 'Частичный возврат ' . $refundAmount . ' руб. от ' . date('d.m.Y') );
// Обновляем статус возвращённых товарных позиций
foreach ($refundItems as $refundItem) {
    $basketItem = getBasketItemById($order, $refundItem['basket_id']);
    if ($basketItem) {
        $basketItem->setField('CUSTOM_PRICE', 'Y');
        // Или создаём отдельную запись в истории возвратов
    }
}
$order->save();

מקרה מהפרקטיקה שלנו: חנות בגדים, החזר חלקי של הזמנה

קונה הזמין מספר פריטים. פריט אחד לא התאים — בוצע החזר חלקי. הממשק הסטנדרטי של Bitrix לא יכול היה להתמודד עם זה: מודול Tinkoff תמך רק בהחזרים מלאים. הלקוח שלנו פנה אלינו.

פתרון: handler החזר מותאם אישית ב-refund. המנהל בוחר פריטים להחזרה → סקריפט PHP יוצר את קבלת ההחזר, קורא ל-payment_refund עם הסכום החלקי, ורושם את התוצאה בשדה הזמנה מותאם אישית. זמן פיתוח: 3 ימים. הפתרון המותאם אישית התברר כפי 2 יותר מהיר ממודולים סטנדרטיים בעיבוד החזרים חלקיים.

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

• ביקורת על תצורת Bitrix הנוכחית ושערי תשלום
• עיצוב ארכיטקטורה להחזר חלקי
• יישום handler מותאם אישית עם אינטגרציית API
• הגדרת יצירת קבלת החזר לפי 54-FZ
• בדיקות על sandbox וייצור
• תיעוד והדרכה למנהלים על הממשק
• אחריות על קוד ותמיכה לאחר השקה

השוואה בין פתרון סטנדרטי למותאם אישית

לוחות זמנים

לוחות הזמנים מעודנים לאחר ניתוח הפתרון הנוכחי שלכם. אנו נעריך את הפרויקט שלכם. להערכת זמן ועלות מדויקת, בקשו ייעוץ — ננתח את התצורה הנוכחית שלכם ונכין הצעה.