שילוב 1C-Bitrix עם שירות התשלומים צ'רפחה (בלארוס)

שילוב 1C-Bitrix עם שירות צ'רפאחה (בלארוס)

בעת חיבור שירות צ'רפאחה ל-1C-Bitrix, מפתחים נתקלים בבעיות טיפוסיות: מטמון לא יציב של אסימון OAuth, חוסר סנכרון של סטטוס הזמנות עקב טיפול לא נכון ב-webhook, והיעדר מנגנון החזרים. כל אחת מהשגיאות הללו עלולה לשתק את קבלת התשלומים ולהוביל לאובדן לקוחות. MTBank מנפיק אסימון עם תוחלת חיים של 3600 שניות — אם המטמון נכשל, החנות מפסיקה ליצור הזמנות. Webhooks חתומים עם HMAC-SHA256, וכל שגיאת הקלדה באלגוריתם האימות מובילה לדחיית הודעות. אנו מכינים את השילוב כך שהמלכודות הללו יישארו בסביבת הבדיקות. לדוגמה, אחד הלקוחות שלנו — חנות מקוונת עם מחזור של 200,000 BYN בחודש — איבד 15% מההזמנות עקב מטמון שגוי. לאחר יישום השילוב שלנו, לא היו דחיות, והחיסכון בעמלות התשלומים עמד על כ-200 BYN בחודש. קבלו ייעוץ בנושא שילוב — נעריך את היקף העבודה תוך יום אחד.

ארכיטקטורת שילוב עם צ'רפאחה

התהליך מחולק למספר שלבים: אימות שותף, יצירת הזמנת תשלומים, וטיפול ב-callback. MTBank משתמש ב-OAuth 2.0 Client Credentials להרשאת שותפים. האתגר המרכזי הוא מטמון אסימון נכון תוך התחשבות בתוחלת חייו וטיפול ב-webhook. השלבים העיקריים:

1. קבלת client_id ו-client_secret מ-MTBank.
2. פריסת לקוח OAuth עם מטמון אסימון ל-3600 שניות עם חיץ של 120 שניות.
3. הגדרת webhooks לקבלת קריאות חוזרות עם אימות חתימת HMAC-SHA256.
4. יישום מטפל תשלומים, החזרים והחזרים חלקיים. להלן יישום מוכח של לקוח OAuth:

class MtbankOAuthClient {
    private ?string $accessToken = null;
    private ?int $expiresAt = null;

    public function getToken(): string {
        if ($this->accessToken && $this->expiresAt > time() + 60) {
            return $this->accessToken;
        }

        $response = $this->httpPost('/oauth/token', [
            'grant_type' => 'client_credentials',
            'client_id' => MTBANK_CLIENT_ID,
            'client_secret' => MTBANK_CLIENT_SECRET,
            'scope' => 'installment',
        ]);

        $this->accessToken = $response['access_token'];
        $this->expiresAt = time() + $response['expires_in'];

        // Кэшируем в Bitrix Cache
        \Bitrix\Main\Data\Cache::createInstance()->set(
            'mtbank_token',
            ['token' => $this->accessToken, 'expires' => $this->expiresAt],
            $response['expires_in'] - 120
        );

        return $this->accessToken;
    }
}

לפי תיעוד MTBank: האסימון מונפק ל-3600 שניות, ולאחר מכן נדרש אימות מחדש?

מטמון עם חיץ של 120 שניות מונע שגיאות בעומסי שיא.

יצירת הזמנת תשלומים

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null) {
    $order = $payment->getOrder();
    $termMap = ['3' => 3, '6' => 6, '12' => 12, '18' => 18, '24' => 24];
    $term = $termMap[$this->getBusinessValue($payment, 'TERM')] ?? 12;
    $payload = [
        'externalOrderId' => 'BITRIX-' . $order->getId(),
        'amount' => (float)$payment->getSum(),
        'currency' => 'BYN',
        'term' => $term,
        'description' => 'Заказ ' . $order->getField('ACCOUNT_NUMBER'),
        'successUrl' => $this->getSuccessUrl($payment),
        'failUrl' => $this->getFailUrl($payment),
        'notifyUrl' => $this->getNotificationUrl($payment),
        'customer' => [
            'firstName' => $order->getPropertyValueByCode('NAME'),
            'lastName' => $order->getPropertyValueByCode('LAST_NAME'),
            'phone' => preg_replace('/\D/', '', $order->getPropertyValueByCode('PHONE')),
            'email' => $order->getPropertyValueByCode('EMAIL'),
        ],
        'items' => $this->formatBasketItems($order->getBasket()),
    ];
    $token = $this->oauthClient->getToken();
    $response = $this->httpPost('/v1/installment/orders', $payload, [
        'Authorization' => "Bearer {$token}",
    ]);
    if (empty($response['paymentUrl'])) {
        throw new \RuntimeException('MTBank Черепаха: пустой paymentUrl');
    }
    // Сохраняем orderId МТБанка для колбэков и возвратов
    \Bitrix\Main\Application::getConnection()->queryExecute(
        "INSERT INTO bl_mtbank_orders (bitrix_order_id, mtbank_order_id, status, created_at) VALUES (?, ?, 'pending', NOW())",
        [$order->getId(), $response['orderId']]
    );
    $result = new \Bitrix\Sale\PaySystem\ServiceResult();
    $result->setPaymentUrl($response['paymentUrl']);
    return $result;
}

עיצוב פריטי סל הקניות

API של MTBank דורש הרכב הזמנה לאימות סכום:

private function formatBasketItems(\Bitrix\Sale\Basket $basket): array
{
    $items = [];
    foreach ($basket as $item) {
        $items[] = [
            'name' => mb_substr($item->getField('NAME'), 0, 255),
            'quantity' => (int)$item->getQuantity(),
            'unitPrice' => round($item->getPrice(), 2),
            'totalPrice'=> round($item->getFinalPrice(), 2),
            'sku' => (string)$item->getProductId(),
        ];
    }
    // Добавляем доставку если есть
    $shipment = $basket->getOrder()->getShipmentCollection()->getIterator()->current();
    $deliveryPrice = $shipment ? $shipment->getPrice() : 0;
    if ($deliveryPrice > 0) {
        $items[] = [
            'name' => 'Доставка',
            'quantity' => 1,
            'unitPrice' => $deliveryPrice,
            'totalPrice' => $deliveryPrice,
            'sku' => 'DELIVERY',
        ];
    }
    return $items;
}

טיפול ב-Callback

MTBank חותם הודעות עם HMAC-SHA256 באמצעות מפתח סודי:

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request) {
    $body = file_get_contents('php://input');
    $signature = $request->getServer()->get('HTTP_X_MTBANK_SIGNATURE');
    $expected = hash_hmac('sha256', $body, MTBANK_WEBHOOK_SECRET);
    if (!hash_equals($expected, $signature ?? '')) {
        http_response_code(400);
        $result = new \Bitrix\Sale\PaySystem\ServiceResult();
        $result->addError(new \Bitrix\Main\Error('Bad signature'));
        return $result;
    }
    $data = json_decode($body, true);
    $result = new \Bitrix\Sale\PaySystem\ServiceResult();
    if ($data['status'] === 'APPROVED') {
        $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING);
        \Bitrix\Main\Application::getConnection()->queryExecute(
            "UPDATE bl_mtbank_orders SET status = 'approved' WHERE mtbank_order_id = ?",
            [$data['orderId']]
        );
        $payment->setPaid('Y');
    }
    return $result;
}

מדוע שילוב מותאם אישית עדיף על מודול מוכן

REST API של MTBank מציע גמישות רבה יותר מכל מודול מוכן: אתם שולטים ברשימת המוצרים, בתנאים ובטיפול בשגיאות. מודולים נוטים לפגר אחרי עדכוני API, בעוד השילוב שלנו מתאים את עצמו לגרסאות Bitrix. בטווח הארוך, פתרון מותאם אישית אמין יותר ויכול לחסוך עד 1,000 BYN בשנה בעמלות באמצעות אופטימיזציה. בנוסף, אנו משתמשים ב-HL-blocks לאחסון יומני עסקאות — זה מאיץ את תהליך הניפוי ומאפשר שחזור מהיר של סטטוס לכל הזמנה. יישמנו למעלה מ-20 שילובי צ'רפאחה בשנים האחרונות, ואף אחד מהם לא דרש חזרה לאחור. בניגוד להחלפת CommerceML הסטנדרטית, השילוב שלנו עובד דרך REST API, מה שמבטל עיכובי סנכרון ומטפל בעד 100 בקשות בשנייה.

טעויות נפוצות בשילוב

• פגיית אסימון באמצע סשן — אם לא מרעננים אותו מראש, הלקוח רואה שגיאה. פתרון: מטמון עם חיץ של 120 שניות.
• אי-התאמה בסכום הסל — אם פריטים מועברים עם שגיאות עיגול, MTBank דוחה את ההזמנה. תמיד לעגל לשתי ספרות, ולהוסיף משלוח כשורה נפרדת.
• חוסר טיפול ב-callback להחזרים — לאחר ביטול הזמנה, הסטטוס לא מתעדכן. אנו מיישמים callback נפרד להחזר וכותבים לאותה טבלת bl_mtbank_orders.
• פורמט מספר טלפון שגוי — MTBank מצפה לספרות בלבד. אנו מיישמים preg_replace('\D', '') כמו בקוד למעלה.

טיפול בהחזרים

API של MTBank תומך בהחזרים מלאים וחלקיים. אנו יוצרים מתודה נפרדת במטפל שקוראת ל-POST /v1/installment/refund עם body {orderId, amount, reason}. התוצאה נשמרת בטבלת bl_mtbank_refunds. אם יוזמים החזר מפאנל הניהול של Bitrix, המטפל שולח אוטומטית את הפקודה ל-MTBank, ועם ה-callback מעדכן את סטטוס ההזמנה. במהלך שנה, עיבדנו למעלה מ-500 החזרים באמצעות מנגנונים כאלה ללא תקלה אחת.

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

אנו מספקים מחזור מלא: החל מבדיקת תהליך התשלום הנוכחי שלכם והגדרת OAuth ועד לבדיקות בסביבת ה-sandbox של MTBank. עם סיום, אתם מקבלים תיעוד על המטפל, קוד מקור (המתארח במאגר שלכם), ואחריות ליציבות למשך חודש. תמיכה שוטפת ופיתוח נוסף זמינים גם כן. השילוב עובד גם על 1C-Bitrix (מהדורת Small Business ומעלה) וגם על Bitrix24 (גרסת on-premise). לצוות שלנו ניסיון רב שנים בשילוב שירותי תשלום עם Bitrix. הזמינו שילוב ובדקו את האמינות.

השוואת גישות

לוח זמנים

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