החזר כספי מלא ב-1C-Bitrix: API, קבלות ועמידה ב-54-FZ

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

במהלך יותר מ-10 שנים ביצענו יותר מ-50 אינטגרציות סולק ונתקלנו בכל הבעיות האופייניות: טוקן שגוי, פורמט סכום לא נכון, קבלת החזר חסרה. מפתחים לעתים קרובות שוכחים ממגבלות ה-API — הדבר מוביל לחסימה.

בחומר זה נבחן כיצד להגדיר החזרים אוטומטיים ללא עבודה ידנית וללא קנסות, תוך שימוש בדוגמאות של Tinkoff, YooKassa ו-Sberbank.

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

מגבלות זמן על החזרים

לסולקים שונים יש מסגרות זמן שונות שבהן החזר אפשרי מבחינה טכנית:

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

• טוקן או חתימת בקשה שגויים.
• קבלה על החזר חסרה (הפרה של 54-FZ).
• חריגה ממגבלת סכום ההחזר.
• סטטוס הזמנה תקוע עקב היעדר טיפול בתגובות.

הוראות הגדרה של החזר צעד אחר צעד

1. יש לזהות את הסולק ואת ה-API שלו. לכל אחד יש פרוטוקול משלו ודרישות משלו לחתימת בקשות.
2. יש לפתח פונקציית wrapper אחת. היא תקרא ל-API הנדרש באמצעות מפתח השער.
3. יש להגדיר בדיקות מגבלות. ב-Tinkoff, למשל, סכום ההחזר המקסימלי לא יכול לעלות על הסכום המקורי.
4. יש לחבר פיסקליזציה. יש ליצור קבלת החזר עם אותם פריטים כמו בקבלה המקורית.
5. יש לבדוק את כל התרחישים: החזר מלא, החזר חלקי, ביטול לפני אישור, וטיפול בשגיאות.

אוטומציה מקצרת את זמן עיבוד ההחזרים משעתיים ביום (עבור 100 החזרים) ל-5 דקות — חיסכון של עד 96% מזמן המנהל.

כיצד להגדיר החזר כספי מלא דרך API?

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

function processRefund(string $gateway, int $paymentId, string $externalId, ?float $amount = null): void {
    switch ($gateway) {
        case 'tinkoff':
            $params = [
                'TerminalKey' => TINKOFF_TERMINAL,
                'PaymentId' => $externalId,
            ];
            $params['Token'] = tinkoffSign($params, TINKOFF_SECRET);
            $result = tinkoffPost('/v2/Cancel', $params);
            if ($result['Status'] === 'REFUNDED') {
                setPaymentRefunded($paymentId);
            }
            break;
        case 'yookassa':
            $refund = $client->createRefund([
                'payment_id' => $externalId,
                'amount' => [
                    'value' => number_format($amount, 2, '.', ''),
                    'currency' => 'USD',
                ],
                'receipt' => buildRefundReceipt($order),
            ], uniqid('', true));
            if ($refund->getStatus() === 'succeeded') {
                setPaymentRefunded($paymentId);
            }
            break;
        case 'sberbank':
            $params = [
                'userName' => SBER_LOGIN,
                'password' => SBER_PASSWORD,
                'orderId' => $externalId,
                'amount' => (int)($amount * 100),
            ];
            $response = file_get_contents(
                'https://securepayments.sberbank.ru/payment/rest/refund.do?' . http_build_query($params)
            );
            $result = json_decode($response, true);
            if ($result['errorCode'] === '0') {
                setPaymentRefunded($paymentId);
            }
            break;
    }
}

מדוע חשוב לעדכן את סטטוס ההזמנה ב-Bitrix?

ללא עדכון סטטוס נכון, ההזמנה תישאר מסומנת כשולמה. הדבר מוביל למשלוח חוזר או לחשבונאות שגויה. אנו משתמשים ב-API הסטנדרטי Bitrix\Sale\Payment:

function setPaymentRefunded(int $paymentId): void {
    $payment = Bitrix\Sale\Payment::loadById($paymentId);
    if (!$payment) return;
    $payment->setPaid('N');
    $payment->setField('PS_STATUS', 'Y');
    $payment->setField('PS_STATUS_CODE', 'refunded');
    $payment->setField('PS_STATUS_MESSAGE', 'Refund from ' . date('d.m.Y H:i'));
    $payment->save();
    $order = $payment->getCollection()->getOrder();
    // Optional: move the order to the "Refund" status
    $order->setField('STATUS_ID', 'RF');
    $order->save();
    sendRefundNotification($order, $payment->getSum());
}

מה כלול בהגדרת ההחזרים?

בעת הזמנת הגדרת החזרים עבור 1C-Bitrix, אנו מספקים:

• ניתוח של אינטגרציית הסולק הנוכחית ותוכנית התשלומים.
• פיתוח של מעטפת API אחודה עבור כל מערכות התשלום הנתמכות.
• הגדרה של יצירת קבלות החזר בהתאם לחוק הפדרלי מס' 54-FZ.
• אינטגרציה עם קופות רושמות מקוונות (ATOL, Shtrikh-M וכדומה) לשליחה אוטומטית של קבלות.
• עדכון סטטוסים של הזמנות ושליחת התראות ללקוחות.
• באופן אופציונלי — הוספה של כפתור "החזר תשלום" לפאנל הניהול.
• בדיקה של כל התרחישים, כולל החזרים חלקיים וטיפול בשגיאות.
• תיעוד עבור הפונקציונליות החדשה.

לוח זמנים — מ-0.5 עד 3 ימים במפתח-על-הכל. אנו נעריך את הפרויקט שלך ונחזור עם עלות מחושבת לאחר ביקורת. הזמן הגדרת החזרים במפתח-על-הכל.

כיצד ליצור נכון קבלת החזר?

אם קופה רושמת מחוברת, ה-API ידחה את הבקשה ללא קבלת החזר. הקבלה משקפת את הקבלה המקורית. פרטים נוספים על דרישות החוק הפדרלי מס' 54-FZ.

function buildRefundReceipt(Bitrix\Sale\Order $order): array {
    $receipt = [
        'customer' => ['email' => getBuyerEmail($order)],
        'items' => []
    ];

    foreach ($order->getBasket() as $item) {
        $receipt['items'][] = [
            'description' => $item->getField('NAME'),
            'quantity' => $item->getQuantity(),
            'amount' => [
                'value' => number_format($item->getPrice(), 2, '.', ''),
                'currency' => 'USD',
            ],
            'vat_code' => getItemVatCode($item),
            'payment_subject' => 'commodity',
            'payment_mode' => 'full_payment',
        ];
    }

    // Delivery as a separate line item
    $deliveryPrice = $order->getDeliveryPrice();
    if ($deliveryPrice > 0) {
        $receipt['items'][] = [
            'description' => 'Delivery',
            'quantity' => 1,
            'amount' => [
                'value' => number_format($deliveryPrice, 2, '.', ''),
                'currency' => 'USD'
            ],
            'vat_code' => 1,
            'payment_subject' => 'service',
            'payment_mode' => 'full_payment',
        ];
    }

    return $receipt;
}

החזרים חלקיים וטיפול בשגיאות

החזרים חלקיים הם צורך נפוץ בעת ביטול מספר פריטים. עבור YooKassa זוהי תכונה סטנדרטית: סכום ההחזר מועבר בשדה amount. עבור Tinkoff ניתן לבצע החזר מלא בלבד של תשלום מאושר. בהחזרים חלקיים חשוב לבדוק מגבלות ולהתאים את הסכום הנותר. טיפול בשגיאות: כל API מחזיר קודים שונים.

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

ממשק מנהל

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

// local/templates/admin/sale_order_detail/refund_button.php
if ($order->isPaid() && $order->getField('STATUS_ID') !== 'RF') {
    echo '<a href="/local/admin/refund.php?order_id=' . $order->getId() . ' class="adm-btn adm-btn-red">Refund payment</a>';
}

ציר זמן להגדרה

אוטומציה של החזרים דרך API מהירה פי 10 מהזנה ידנית של נתונים בחשבון האישי בבנק שלך. צור קשר כדי לדון בהגדרת החזרים לפרויקט שלך. קבל ייעוץ בנושא אינטגרציה של סולקים עם פיסקליזציה אוטומטית. הניסיון שלנו — למעלה מ-10 שנים של עבודה עם Bitrix ולמעלה מ-50 אינטגרציות עם מערכות תשלום.

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