Часткове повернення на 1С-Бітрікс: інтеграція API та фіскалізація чека

Часткове повернення в інтернет-магазині на Бітрікс — технічно складне завдання. Одна позиція бракована, інша не підійшла за розміром: потрібно повернути не всю суму, а лише частину, коректно перерахувати чек згідно 54-ФЗ та оновити статуси. Помилка в чеку тягне суттєві штрафи. Наш досвід впровадження таких рішень — понад 10 років, і ми гарантуємо коректну роботу з фіскальними даними. Якщо ви зіткнулися з помилками часткового повернення, отримайте консультацію нашого інженера.

Чому часткове повернення — нетривіальне завдання для Бітрікс?

Стандартні модулі Бітрікс часто підтримують лише повне повернення. Згідно документації 1С-Бітрікс по модулю Sale, для часткового повернення потрібна кастомна розробка: інтеграція з API платіжних систем, формування чека повернення згідно 54-ФЗ та оновлення статусів у модулі Sale. Без якісної реалізації можливі розбіжності між сумою повернення та чеком, що призводить до блокування каси податковою. У 95% випадків помилка пов'язана з неспівпадінням суми повернення та суми в чеку.

Де виконується часткове повернення

Часткове повернення ініціюється магазином через API платіжної системи. Покупець звертається в підтримку, менеджер обробляє повернення в адміністративній панелі Бітрікс — або через стандартний інтерфейс (якщо модуль підтримує), або через кастомний обробник. Ми реалізуємо зручний інтерфейс для менеджера з вибором позицій та автоматичним формуванням запитів.

Як переконатися, що чек повернення коректний?

Ключовий момент — сума позицій у чеку повинна точно збігатися з сумою повернення. Навіть копійчана розбіжність призведе до помилки ОФД. Ми використовуємо автоматичну верифікацію перед відправкою: порівнюємо підсумкову суму із запитаною, при неспівпадінні — блокуємо відправку та виводимо попередження. Це виключає штрафи. Додатково впроваджуємо логування всіх запитів для аудиту.

API повернення: приклади

Тінькофф:

$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' — успешный возврат 

ЮKassa:

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-ФЗ)

Якщо підключено онлайн-касу, часткове повернення потребує передачі чека повернення в ОФД. Структура чека повернення ідентична вихідному, але:

• type документа: refund (в АТОЛ), payment_refund (в ЮKassa)
• У чек включаються тільки позиції, що повертаються, з сумами, що повертаються
• Сума позицій у чеку повинна точно збігатися з сумою повернення

// Пример чека возврата для ЮKassa $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, 'Расхождение суммы чека!'); 

Оновлення статусів у Бітрікс

Після успішного повернення потрібно оновити стан у модулі Sale:

// Частичный возврат — не ставим оплату как "возвращена" полностью // Только записываем сумму возврата и обновляем статус товарной позиции $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(); 

Кейс з нашої практики: магазин одягу, повернення частини замовлення

Покупець замовив 3 позиції на $76–110. Одна позиція не підійшла за розміром — повернення $19–27. Через стандартний інтерфейс Бітрікс повернення не проходило: модуль Тінькофф підтримував лише повне повернення. Наш клієнт звернувся до нас.

Рішення: кастомний обробник повернень у /local/. Менеджер вибирає позиції для повернення → PHP-скрипт формує чек повернення, викликає /v2/Cancel з частковою сумою, фіксує результат у користувацькому полі замовлення. Час розробки: 3 дні. Кастомне рішення виявилося в 2 рази швидшим за стандартні модулі при обробці часткових повернень.

Що входить до роботи

• Аудит поточної конфігурації Бітрікс та платіжних шлюзів
• Проектування архітектури часткового повернення
• Реалізація кастомного обробника з інтеграцією API
• Налаштування формування чека повернення згідно 54-ФЗ
• Тестування на пісочниці та бойовому контурі
• Документація та навчання менеджерів роботі з інтерфейсом
• Гарантія на код і підтримка після впровадження

Порівняння стандартного та кастомного рішення

Терміни

Терміни уточнюються після аналізу вашого поточного рішення. Ми оцінимо проект безкоштовно. Для точного розрахунку термінів та вартості замовте консультацію — ми безкоштовно проаналізуємо вашу поточну конфігурацію та підготуємо пропозицію.