שילוב 1C-Bitrix עם דואר רוסיה: API, נורמליזציה, מנות

1C-Bitrix אינטגרציה עם דואר רוסיה: API, נורמליזציה, מנות

כאשר חנות Bitrix מתחילה לספק הזמנות לאזורים מרוחקים, שירותי שליחים לרוב חסרי אונים — אין כיסוי?

המפעיל היחיד שמגיע לכל יישוב הוא דואר רוסיה. אבל אינטגרציה עם ה-API שלו Otpravka 2.0 אינה רק בקשת POST. היא כוללת אימות דו-שלבי, נורמליזציה חובה של כתובות לפי FIAS, מצב אצווה, ומזומן במשלוח. ללא הבנת הניואנסים הללו, חבילות יוצאות עם שגיאות, וכסף נתקע בחשבונות. החיסכון הממוצע בהחזרות לאחר יישום נורמליזציה הוא 15%, ומהירות עיבוד ההזמנות מוכפלת. בפרויקט אחד, החיסכון החודשי עמד על $1.1k–1.6k. השלמנו עשרות אינטגרציות כאלה והרכבנו פתרון טיפוסי. צרו קשר לייעוץ כדי להעריך את הפרויקט שלכם ביום אחד.

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

דואר רוסיה API: עקרונות פעולה

כתובת בסיס: https://otpravka-api.pochta.ru. אימות: שני טוקנים בו זמנית — Authorization: AccessToken TOKEN ו-X-User-Authorization: Basic BASE64(login:password). כדי לקבל טוקנים, יש להירשם בחשבון האישי של דואר רוסיה וליצור אפליקציה. AccessToken מונפק אוטומטית, ואימות Basic נוצר מהשם והסיסמה בפורמט Base64. פרטים נוספים בתיעוד ה-API הרשמי.

קבוצות שיטות עיקריות:

• /1.0/user/shipping-points — כתובות שולח (מאיפה)
• /1.0/clean/address — נורמליזציה של כתובות
• /1.0/tariff — חישוב תעריף
• /1.0/user/backlog — העלאת מנות באצווה
• /1.0/batch/{batchName}/shipment — יצירת מנות באצווה
• /1.0/shipment/search — מעקב לפי ברקוד

איך פועלת נורמליזציה של כתובות?

נקודת הכאב המרכזית של דואר רוסיה היא איכות הכתובות שהלקוחות מזינים. ה-API דורש כתובות נכונות בפורמט FIAS. נורמליזציה היא הצעד הראשון לפני כל פעולה. אם הכתובת לא עברה נורמליזציה (quality-code אינו GOOD), לא ניתן לשלוח את החבילה — היא לא תעבור מיון. הלקוחות שלנו חוסכים עד 15% בהחזרות בזכות בדיקה זו.

private function normalizeAddress(string $rawAddress): array
{
    $response = $this->apiPost('/1.0/clean/address', [
        [
            'id' => 'addr1',
            'original-address' => $rawAddress,
        ],
    ]);
    $normalized = $response[0] ?? [];
    if (($normalized['quality-code'] ?? '') === 'GOOD') {
        return $normalized;
    }
    // Если качество плохое — возвращаем ошибку, не создаём отправление
    throw new \RuntimeException(
        'Адрес не нормализован: ' . ($normalized['quality-code'] ?? 'unknown')
    );
}

קודי איכות: private function normalizeAddress(string $rawAddress): array { $response = $this->apiPost('/1.0/clean/address', [ [ 'id' => 'addr1', 'original-address' => $rawAddress, ] ]); $normalized = $response[0] ?? []; if (($normalized['quality-code'] ?? '') === 'GOOD') { return $normalized; } // Если качество плохое — возвращаем ошибку, не создаём отправление throw new \RuntimeException( 'Адрес не нормализован: ' . ($normalized['quality-code'] ?? 'unknown') ); } — נורמליזציה מלאה, GOOD — תיבת דואר, POSTAL_BOX — דואר עד הבית, ON_DEMAND — בעיות נורמליזציה שונות. רק UNDEF_* מבטיח משלוח נכון.

איך לחשב תעריף?

private function calcTariff( array $normalizedAddress, int $weightGram, string $mailType = 'POSTAL_PARCEL' ): float {
    $response = $this->apiPost('/1.0/tariff', [
        'object-type' => $mailType,
        'mail-category' => 'ORDINARY',
        'from-index' => $this->getOption('FROM_INDEX'), // индекс отправки
        'to-index' => $normalizedAddress['index'],
        'mass' => $weightGram,
        'dimension' => [
            'height' => 200,
            'length' => 300,
            'width' => 200,
        ],
    ]);
    return ($response['total-rate'] ?? 0) / 100; // копейки → доллары
}

דואר רוסיה מחזיר את העלות בקופיקות — אל תשכחו לחלק ב-100. סוגי מנות: GOOD (חבילה), private function calcTariff( array $normalizedAddress, int $weightGram, string $mailType = 'POSTAL_PARCEL' ): float { $response = $this->apiPost('/1.0/tariff', [ 'object-type' => $mailType, 'mail-category' => 'ORDINARY', 'from-index' => $this->getOption('FROM_INDEX'), // индекс отправки 'to-index' => $normalizedAddress['index'], 'mass' => $weightGram, 'dimension' => [ 'height' => 200, 'length' => 300, 'width' => 200, ], ]); return ($response['total-rate'] ?? 0) / 100; // копейки → доллары } (אקספרס), POSTAL_PARCEL (EMS אופטימלי), EMS (מחלקה ראשונה). השוואת תעריפים מראה ש-EMS_OPTIMAL מהיר ב-30% מחבילה רגילה בעלות דומה.

למה מצב אצווה הוא חובה?

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

public function createShipment(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    // 1. Получаем или создаём партию
    $batchName = $this->getOrCreateBatch($shipment);

    // 2. Создаём отправление в партии
    $payload = [[
        'address-type-to' => 'DEFAULT',
        'mail-type' => 'POSTAL_PARCEL',
        'mail-category' => 'ORDINARY',
        'mass' => $this->getWeight($shipment),
        'index-to' => $this->getNormalizedIndex($props),
        'recipient-name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
        'tel-address' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'str-index-to' => $this->getNormalizedIndex($props),
        'order-num' => (string)$order->getId(),
        'payment' => $this->getCashOnDelivery($order), // наложенный платёж
    ]];

    $response = $this->apiPost("/1.0/batch/{$batchName}/shipment", $payload);
    $barcode = $response['result-ids'][0] ?? null;

    if ($barcode) {
        $props->getItemByOrderPropertyCode('POCHTA_BARCODE')?->setValue($barcode);
        $order->save();
    }

    return $barcode ?? '';
}

איך לבצע אינטגרציה שלב אחר שלב

1. קבלת טוקני גישה בחשבון האישי של דואר רוסיה.
2. יישום נורמליזציה של כתובות במהלך תהליך ההזמנה.
3. יישום חישוב תעריף בזמן אמת.
4. הגדרת יצירת מנות באצווה.
5. חיבור מעקב ועדכוני סטטוס.
6. ארגון הדפסת בולים וטפסים.

מזומן במשלוח

מזומן במשלוח (COD) הוא פונקציה מרכזית של דואר רוסיה למסחר אלקטרוני. השדה EMS_OPTIMAL בבקשה מכיל את הסכום לגבייה מהלקוח בקופיקות. אם אין צורך ב-COD — העבירו FIRST_CLASS. עם COD, דואר רוסיה גובה עמלה של כ-2–3% ומעביר את היתרה לחשבון הבנק של החנות. זמן העברה עד 10 ימי עסקים. חיסכון במשלוח בעת שימוש ב-COD הודות לאוטומציה מגיע עד 20%, שבמונחים כספיים יכול להסתכם ב-$450–650 עם מחזור של $4.5k–6.5k.

מעקב דרך דואר רוסיה API

לעדכוני סטטוס אוטומטיים, אנו משתמשים במשימות cron המופעלות פעם בשעה.

public function trackShipment(string $barcode): array
{
    $response = $this->apiGet('/1.0/shipment/search', ['query' => $barcode]);
    $events = $response['trackingData']['trackingItem']['trackingHistoryItem'] ?? [];
    $lastEvent = end($events);
    return [
        'status' => $lastEvent['humanStatus'] ?? '',
        'date' => $lastEvent['eventDateTime'] ?? '',
        'city' => $lastEvent['cityName'] ?? '',
        'barcode' => $barcode,
    ];
}

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

הדפסת בולים וטפסים

לאחר הוספת מנות לאצווה, זמינה הדפסה של f7 (תווית כתובת) ו-f107/f112 (מסמכים נלווים):

GET /1.0/forms/{barcode}/f7pdf — адресный ярлык GET /1.0/batch/{batchName}/checkin — сдача партии на почту 

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

אנו משתמשים ב-HL-blocks לאחסון הגדרות אינטגרציה ובתיוג מטמון (tagged caching) למטמון.

לוח זמנים משוער

אינטגרציה מלאה אורכת 5 עד 8 ימים בהתאם למורכבות הקטלוג ולדרישות האישיות. הפיכות — בעת מעבר לשירות משלוח אחר, המודול מוחלף בקלות.

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