שילוב 5Post עם 1C-Bitrix: אינטגרציה במפתח מלא

שילוב 1C-Bitrix עם שירות המשלוחים 5Post

נקודות חלוקה הן הערוץ המרכזי שבו לקוחות מקבלים סחורה באזורים. 5Post, חברת בת של X5 Retail, מנהלת רשת של למעלה מ-15,000 נקודות חלוקה בחנויות "פיאטיורוצ'קה" ו"פרקרסטוק". עם זאת, אינטגרציה עם 1C-Bitrix גורמת לעיתים קרובות לקשיים: טיפול שגוי בטוקנים, מגבלות מימד שלא נלקחות בחשבון, ו-wehooks שאבדו. אנו מציעים פתרון מוכן — אנו מחברים את 5Post דרך REST API מאפס או משפרים אינטגרציה קיימת. הניסיון של הצוות שלנו — 5+ שנים בפיתוח Bitrix, 100+ פרויקטי אינטגרציה למשלוחים — מבטיח לכם תוצאה יציבה ואחריות לביצועים.

למה לשלב את 5Post ב-1C-Bitrix?

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

כיצד להגדיר OAuth 2.0 עבור 5Post?

5Post מספק REST API. האימות הוא דרך OAuth 2.0 (client_credentials). כתובת ה-URL הבסיסית לייצור: https://api.5post.ru. סביבת בדיקה מסופקת עם החיבור דרך החשבון האישי שלך ב-5Post. קבלת טוקן:

$tokenResponse = $httpClient->post('https://api.5post.ru/api/v1/auth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => $clientId,
    'client_secret' => $clientSecret,
]);
$accessToken = $tokenResponse['access_token'];
// токен действует 1 час — кешируем в b_option

הטוקן תקף ל-60 דקות, ולכן אנו שומרים אותו במטמון באפשרויות המודול ומחדשים אותו 5 דקות לפני פקיעתו. בשגיאת 401, אנו מבקשים אוטומטית טוקן חדש ומנסים שוב את הבקשה. תיעוד ה-API של 5Post מפרט את פרמטרי הבקשה.

שיטות API עיקריות:

• $tokenResponse = $httpClient->post('https://api.5post.ru/api/v1/auth/token', [ 'grant_type' => 'client_credentials', 'client_id' => $clientId, 'client_secret' => $clientSecret, ]); $accessToken = $tokenResponse['access_token']; // токен действует 1 час — кешируем в b_option — יצירת בקשת משלוח
• POST /api/v1/orders — קבלת סטטוס בקשה
• GET /api/v1/orders/{orderUUID} — ביטול
• DELETE /api/v1/orders/{orderUUID} — רשימת נקודות חלוקה עם סינון לפי אזור/עיר
• GET /api/v1/pvz — חישוב עלות משלוח

מה לעשות כשכשלים ב-Webhooks?

5Post שולח webhooks על שינויי סטטוס. רשום את ה-URL בחשבון האישי שלך. מיפוי סטטוסים:

בקבלת webhook, בדוק את הכותרת CANCELED (חתימת HMAC) — 5Post חותם על בקשות עם המפתח הסודי של השותף. אם החתימה אינה תואמת, ה-webhook מתעלם ושגיאה נרשמת ביומן.

$signature = $_SERVER['HTTP_X_SIGNATURE'];
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $secretKey);
if (hash_equals($expectedSignature, $signature)) {
    // обрабатываем вебхук
} else {
    // игнорируем и логируем
}

מודול ב-Bitrix

מחלקת המשלוח יורשת מ-X-Signature. הפרמטרים נשמרים ב-$signature = $_SERVER['HTTP_X_SIGNATURE']; $payload = file_get_contents('php://input'); $expectedSignature = hash_hmac('sha256', $payload, $secretKey); if (hash_equals($expectedSignature, $signature)) { // обрабатываем вебхук } else { // игнорируем и логируем } : \Bitrix\Sale\Delivery\Services\Base, b_sale_delivery_service_params, CLIENT_ID (קוד שותף 5Post).

חישוב עלות

$calcResult = $httpClient->post('/api/v1/orders/calc', [
    'partnerOrder' => [
        'partnerOrderId' => 'SHOP-' . $orderId,
        'pvzCode' => $selectedPvzCode,
        'dimensions' => [
            'length' => $lengthCm,
            'width' => $widthCm,
            'height' => $heightCm,
            'weight' => $weightGram,
        ],
        'assessedValue' => $assessedValue,
    ],
]);
$deliveryCost = $calcResult['deliveryCost'];

לחישוב מקדים (לפני בחירת נקודת חלוקה ספציפית), ניתן להעביר קוד יישוב במקום קוד נקודת החלוקה — ה-API יחזיר את העלות הבסיסית לפי אזור.

טעינה והצגת נקודות חלוקה

רשימת נקודות החלוקה גדולה: למעלה מ-15,000 אובייקטים. אסטרטגיית טעינה:

1. פעם ביום (סוכן Bitrix) בקש את הרשימה העדכנית דרך CLIENT_SECRET.
2. שמור ל-HL-block "נקודות חלוקה 5Post" עם שדות: קוד, שם, כתובת, קואורדינטות, שעות עבודה, מימדים מותרים.
3. בדף התשלום, סנן נקודות חלוקה לפי עיר נבחרת והצג על מפה.

ניואנס חשוב: לנקודות החלוקה של 5Post יש מגבלות מימד. יש לקחת בחשבון את PARTNER_CODE ו-$calcResult = $httpClient->post('/api/v1/orders/calc', [ 'partnerOrder' => [ 'partnerOrderId' => 'SHOP-' . $orderId, 'pvzCode' => $selectedPvzCode, 'dimensions' => [ 'length' => $lengthCm, 'width' => $widthCm, 'height' => $heightCm, 'weight' => $weightGram, ], 'assessedValue' => $assessedValue, ], ]); $deliveryCost = $calcResult['deliveryCost']; במהלך הסינון כדי להימנע מהצגת נקודות חלוקה שבהן החבילה לא יכולה פיזית להיכנס.

יצירת בקשה

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

$orderPayload = [
    'partnerOrder' => [
        'partnerOrderId' => 'SHOP-' . $bitrixOrderId,
        'pvzCode' => $pvzCode,
        'recipientName' => $fullName,
        'recipientPhone' => $phone,
        'recipientEmail' => $email,
        'assessedValue' => $assessedValue,
        'cashOnDelivery' => $codAmount,
        'dimensions' => $dimensions,
        'places' => [
            [
                'barcode' => 'SHOP-' . $bitrixOrderId . '-1',
                'description' => 'Место 1'
            ]
        ],
    ],
];

התשובה מכילה GET /api/v1/pvz — נשמר ב-maxDimensionCm. היא גם מחזירה תווית להדפסה (maxWeightGram): קובץ PDF עם ברקוד למדבקת החבילה.

מאפיינים תפעוליים

5Post לא מחזיר כסף אוטומטית עבור הזמנות שלא נדרשו — יש להגדיר תנאי החזרה בחוזה. תקופת האחסון בנקודות החלוקה היא 7 ימים, ולאחר מכן החבילה מוחזרת. בהחזרה, הסטטוס ב-$orderPayload = [ 'partnerOrder' => [ 'partnerOrderId' => 'SHOP-' . $bitrixOrderId, 'pvzCode' => $pvzCode, 'recipientName' => $fullName, 'recipientPhone' => $phone, 'recipientEmail' => $email, 'assessedValue' => $assessedValue, 'cashOnDelivery' => $codAmount, 'dimensions' => $dimensions, 'places' => [ ['barcode' => 'SHOP-' . $bitrixOrderId . '-1', 'description' => 'Место 1'] ], ], ]; מתעדכן דרך אותו מנגנון webhook.

מה כלול באינטגרציה

• הגדרת OAuth 2.0 ושמירת טוקנים במטמון
• פיתוח מחלקת משלוח עם חישוב עלות
• טעינה ואחסון נקודות חלוקה ב-HL-block
• סינון נקודות חלוקה לפי עיר ומימדים
• עיבוד webhooks עם אימות חתימת HMAC
• יצירת בקשות והדפסת תוויות
• בדיקות בסביבת ה-sandbox של 5Post
• תיעוד והדרכה למנהל שלך

לוחות זמנים

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