שילוב YooKassa עם 1C-Bitrix: מטפלים מותאמים אישית ו-54-FZ

שילוב תשלומי YooKassa ב-1C-Bitrix

תארו לעצמכם: לקוח מבצע הזמנה, עובר לתשלום — אבל לאחר עסקה מוצלחת, ה-webhook אף פעם לא מגיע, סטטוס ההזמנה לא מתעדכן, והכסף תקוע בחוסר ודאות. YooKassa (לשעבר Yandex.Kassa) הוא אחד מאגרגטורי התשלום הפופולריים ביותר ברוסיה, אך המודול הסטנדרטי מ-Marketplace לא מכסה את כל התרחישים. נתקלנו במצבים שבהם התראות לא הגיעו, החזרים נכשלו עם שגיאות, והפיסקליזציה הפיקה קבלות לא תקינות. לפי התיעוד הרשמי של YooKassa, גרסת REST API 3 מאפשרת ניהול גמיש של עסקאות אך דורשת הגדרה קפדנית. במשך למעלה מחמש שנים, השלמנו יותר מ-50 אינטגרציות — מחנויות פשוטות ועד פלטפורמות B2B עם עשרות אלפי עסקאות חודשיות. להלן, אנו מפרקים את הפרטים הטכניים ומראים כיצד להימנע ממלכודות נפוצות.

כיצד YooKassa עובד טכנית

YooKassa מספק REST API (api.yookassa.ru/v3/). זרימת התשלום הקלאסית:

1. החנות שולחת POST /payments עם סכום, מטבע ו-confirmation.type=redirect — YooKassa מחזיר payment.id ו-confirmation.confirmation_url.
2. הלקוח מופנה לדף התשלום של YooKassa.
3. לאחר התשלום, YooKassa שולח התראת webhook ל-return_url ו-POST לכתובת ה-URL המוגדרת להתראות.
4. החנות קוראת ל-GET /payments/{id} לצורך אימות סטטוס סופי.

אימות: HTTP Basic עם shopId:secretKey או אסימון OAuth.

אמצעי תשלום נתמכים: כרטיסי בנק, SBP, YooMoney, SberPay, Tinkoff, QIWI (עם מגבלות), מזומן דרך מסופים. השיטה מועברת ב-payment_method_type או נבחרת על ידי הלקוח בטופס YooKassa.

למה לבחור באינטגרציה מותאמת אישית

המודול הרשמי של YooKassa עבור Bitrix זמין בחינם ועובד עבור חנויות סטנדרטיות. עם זאת, יש לו מגבלות: קישור נוקשה לרכיבים סטנדרטיים, קושי בהתאמת סטטוסי הזמנה, וחוסר גמישות בפיסקליזציה. מטפל מותאם אישית פותר בעיות אלו ומאפשר שילוב YooKassa עם כל ישויות לא סטנדרטיות. הניסיון שלנו מראה שאינטגרציה מותאמת אישית מטפלת במשימות לא סטנדרטיות פי 2-3 מהר יותר מאשר שינוי המודול המוכן. אנו מומחים מוסמכים עם ניסיון של למעלה מ-5 שנים, המבטיחים פעולה תקינה בכל התרחישים. צרו קשר כדי להעריך את הפרויקט שלכם — קבלו ייעוץ על אינטגרציה ולוחות זמנים מדויקים למקרה שלכם.

כיצד להגדיר Webhooks עבור YooKassa

YooKassa שולח POST לכתובת ה-URL המוגדרת בכל פעם שסטטוס התשלום משתנה. ב-Bitrix, כתובת ה-URL של המטפל ברירת המחדל היא /bitrix/tools/sale_ps_result.php. נקודות קריטיות:

• אמתו את כתובת ה-IP של המקור. YooKassa מפרסם את טווחי ה-IP שלו: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35. ללא סינון, אתם מסתכנים בהתראות מזויפות.
• אמתו את הסטטוס דרך ה-API. אל תסמכו על נתוני webhook ישירות — בצעו GET /payments/{id} לבדיקה כפולה.
• טפלו רק בסטטוסים סופיים. pending ו-waiting_for_capture אינם דורשים שינויי הזמנה.

// Пример обработки
$body = file_get_contents('php://input');
$notification = json_decode($body, true);
$payment = $client->getPaymentInfo($notification['object']['id']);

switch ($payment->getStatus()) {
    case 'succeeded':
        $bitrixPayment->setPaid('Y');
        $bitrixPayment->save();
        break;
    case 'canceled':
        // Записываем причину отмены
        break;
}

פרמטרי בקשה מרכזיים

// Минимальный запрос на создание платежа через SDK
use YooKassa\Client;

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

$payment = $client->createPayment([
    'amount' => [
        'value' => number_format($order->getPrice(), 2, '.', ''),
        'currency' => 'RUB',
    ],
    'confirmation' => [
        'type' => 'redirect',
        'return_url' => 'https://shop.ru/personal/order/detail/' . $order->getId() . '/',
    ],
    'capture' => true, // false для двухстадийных платежей
    'description' => 'Заказ №' . $order->getAccountNumber(),
    'metadata' => ['bitrix_order_id' => $order->getId()],
    'receipt' => $receiptData, // обязательно при подключённой кассе
], uniqid('', true)); // idempotency key

// Пример обработки $body = file_get_contents('php://input'); $notification = json_decode($body, true); $payment = $client->getPaymentInfo($notification['object']['id']); switch ($payment->getStatus()) { case 'succeeded': $bitrixPayment->setPaid('Y'); $bitrixPayment->save(); break; case 'canceled': // Записываем причину отмены break; } — תשלום חד-שלבי, הכסף נגבה מיד. // Минимальный запрос на создание платежа через SDK use YooKassa\Client; $client = new Client(); $client->setAuth($shopId, $secretKey); $payment = $client->createPayment([ 'amount' => [ 'value' => number_format($order->getPrice(), 2, '.', ''), 'currency' => 'RUB', ], 'confirmation' => [ 'type' => 'redirect', 'return_url' => 'https://shop.ru/personal/order/detail/' . $order->getId() . '/', ], 'capture' => true, // false для двухстадийных платежей 'description' => 'Заказ №' . $order->getAccountNumber(), 'metadata' => ['bitrix_order_id' => $order->getId()], 'receipt' => $receiptData, // обязательно при подключённой кассе ], uniqid('', true)); // idempotency key — דו-שלבי: YooKassa מחזיק את הסכום, והחנות קוראת ל-capture: true בעת המשלוח.

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

פיסקליזציה (54-FZ) ולמה היא חובה

הדרישות של 54-FZ (על שימוש בציוד קופה רושמת) חלות על כל התשלומים המקוונים. YooKassa פועל כרשם פיסקלי, ושולח נתונים ל-OFD. אם החוזה שלכם עם YooKassa כולל העברת קבלות, אובייקט capture: false בבקשה הופך לחובה. בלעדיו, העסקה תידחה — זו אחת הבעיות הנפוצות ביותר. מבנה הקבלה חייב להתאים בדיוק לדרישות 54-FZ. אנו משתמשים בסכמה מוכחת עם פירוט לפי שיעורי מע"מ ומאפייני פריטים. הסכום הכולל של כל הפריטים בקבלה חייב להתאים בדיוק לסכום התשלום — YooKassa בודק זאת בצד שלהם. החזרים דורשים גם קבלה המשקפת את הפריטים המקוריים. התיעוד הרשמי של YooKassa מספק דוגמאות למבנה קבלה, אך אנו מתאימים אותן לפרטים הספציפיים שלכם.

סטטוסי תשלום והחזרים

YooKassa תומך בהחזרים חלקיים ומלאים דרך canceled. אם קופה רושמת מחוברת, החזר ללא קבלה נדחה. קבלת ההחזר משקפת את פריטי הקבלה המקורית עם סוג cancellation_details. יישמנו למעלה מ-50 אינטגרציות מוצלחות עם החזרים, המבטיחות חשבונאות נכונה.

בדיקות

YooKassa מספק סביבת בדיקה עם אותם endpoints. במצב בדיקה (refund), התשלומים מתבצעים עם כרטיסי בדיקה:

• canceled — תשלום מוצלח
• shopId=test_... — דחייה

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

מה כלול

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

לוחות זמנים וכיצד להתחיל

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