ПЭК у Бітрікс: розрахунок, створення замовлень, трекінг

ПЭК у Бітрікс: розрахунок, створення замовлень, трекінг

ПЭК (Перша Експедиційна Компанія) — одна з ключових транспортних компаній для вантажної та збірної доставки в Росії. Основна специфіка інтеграції: ПЭК працює з вантажами від 1 кг і вище, API заточений під параметри вантажомісця (довжина, ширина, висота, вага кожного місця окремо), а не під стандартний роздрібний формат Бітрікс. Якщо у вас інтернет-магазин з великогабаритом — дивани, будівельні матеріали, промислове обладнання — ПЭК часто стає основним перевізником.

З нашої практики: ми реалізували інтеграцію для мережі магазинів будматеріалів — розрахунок став точнішим на 25%, а донарахування припинилися. Досвід 5+ років у Бітрікс та понад 30 проєктів з доставки гарантують надійне рішення.

API ПЭК: особливості

ПЭК надає REST API з авторизацією через Bearer-токен. Токен отримується через POST /v2/sign-in з логіном і паролем з особистого кабінету. Токен не має жорстко обмеженого TTL (на практиці живе 24–48 годин), але рекомендується кешувати та оновлювати при отриманні 401.

Ключові ендпоінти:

• POST /v2/calculator — розрахунок вартості та термінів
• POST /v2/orders — створення замовлення
• GET /v2/orders/{id} — статус замовлення
• GET /v2/departments — список терміналів ПЭК

Базовий URL: https://api.pek.ru. Документація доступна в особистому кабінеті партнера.

Як налаштувати розрахунок вартості?

class PekDeliveryHandler extends \Bitrix\Sale\Delivery\Services\Base { protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $token = $this->getApiToken(); $payload = $this->buildCalcPayload($shipment); $response = $this->apiPost('/v2/calculator', $payload, $token); if (empty($response['price'])) { $result->addError(new \Bitrix\Main\Error('Розрахунок недоступний')); return $result; } $result->setDeliveryPrice((float)$response['price']); $result->setPeriodDescription($response['period_min'] . '–' . $response['period_max'] . ' днів'); return $result; } private function buildCalcPayload(\Bitrix\Sale\Shipment $shipment): array { $order = $shipment->getOrder(); return [ 'senderCityId' => (int)$this->getOption('SENDER_CITY_ID'), 'receiverCityId' => $this->getReceiverCityId($shipment), 'cargo' => $this->buildCargoPlaces($shipment), 'service' => $this->getOption('SERVICE_TYPE', 'door_door'), 'declaredValue' => round($order->getPrice(), 2), ]; } private function buildCargoPlaces(\Bitrix\Sale\Shipment $shipment): array { // ПЭК вимагає параметри кожного вантажомісця окремо $weight = max($shipment->getWeight() / 1000, 1); // г → кг, мінімум 1 кг return [ [ 'weight' => $weight, 'length' => (int)$this->getOption('DEFAULT_LENGTH', 50), 'width' => (int)$this->getOption('DEFAULT_WIDTH', 50), 'height' => (int)$this->getOption('DEFAULT_HEIGHT', 50), ], ]; } } 

Важно: ПЭК розраховує за об'ємною вагою. Якщо фактична вага менша за об'ємну (Д×Ш×В / 5000 для авіа, / 4000 для авто), рахується об'ємна. Для великогабариту це критично — передавайте реальні габарити товарів. Документація ПЭК: об'ємна вага = (Д×Ш×В)/5000 для авіа та /4000 для авто.

Як отримати cityId і не помилитися?

ПЭК використовує власні числові ідентифікатори міст. Пошук міста:

public function findCityId(string $cityName): ?int { $response = $this->apiGet('/v2/city?name=' . urlencode($cityName), $this->getApiToken()); return $response[0]['id'] ?? null; } 

Альтернатива: вивантажити довідник міст ПЭК і зберігати мапінг назва_міста → pek_city_id в інфоблоці або кастомній таблиці. При старті рекомендується саме цей підхід — API пошуку міста повертає неоднозначні результати для населених пунктів з однаковою назвою.

Створення замовлення та термінали

private function createPekOrder(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $payload = [ 'senderCityId' => (int)$this->getOption('SENDER_CITY_ID'), 'receiverCityId' => $this->getReceiverCityId($shipment), 'cargo' => $this->buildCargoPlaces($shipment), 'service' => $this->getOption('SERVICE_TYPE', 'door_door'), 'declaredValue' => round($order->getPrice(), 2), 'sender' => [ 'company' => $this->getOption('SENDER_COMPANY'), 'contact' => $this->getOption('SENDER_CONTACT'), 'phone' => $this->getOption('SENDER_PHONE'), 'address' => $this->getOption('SENDER_ADDRESS'), ], 'receiver' => [ 'contact' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), ], ]; $response = $this->apiPost('/v2/orders', $payload, $this->getApiToken()); return (string)($response['id'] ?? ''); } 

При типі door_terminal або terminal_door потрібно передавати ідентифікатор терміналу ПЭК. Список терміналів: GET /v2/departments. Фільтрація за cityId. На сайті реалізується випадаючий список терміналів з картою — віджет або кастомна реалізація на Leaflet/Yandex Maps.

Чому важливо передавати реальні габарити?

Кейс з нашої практики: магазин будматеріалів, середня вага замовлення 50–200 кг, багато листового матеріалу. Проблема при впровадженні: Бітрікс зберігає вагу відправлення як одне число, а ПЭК при замовленні з кількома позиціями різних розмірів вимагає список вантажомісць з габаритами кожного. Довелося реалізувати логіку розбивки: у кожного товару в інфоблоці заведено властивості DELIVERY_LENGTH, DELIVERY_WIDTH, DELIVERY_HEIGHT. При формуванні відправлення кожна одиниця товару перетворюється на окреме вантажомісце.

Це збільшило точність розрахунку: розбіжність з реальною вартістю скоротилася з ±30% до ±5%, економія на донарахуваннях склала до 15% від вартості доставки. Така деталізація — ключова перевага перед стандартним підходом, де використовується усереднена вага.

Трекінг статусів

Вебхуків у ПЭК немає — тільки polling. Агент Бітрікс раз на 4 години запитує статуси активних відправлень через GET /v2/orders/{id} та оновлює статус замовлення в магазині. Наш досвід показує, що polling простіший і дешевший за вебхуки для невисоких навантажень (до 500 відправлень на день).

Типові помилки при інтеграції

Що входить в роботу під ключ

• Розробка обробника доставки на PHP 8.1+ з повним циклом: розрахунок → створення → трекінг.
• Налаштування відповідності міст ПЭК (вивантаження та мапінг).
• Генерація вантажомісць на основі властивостей товарів (якщо потрібно).
• Інтеграція карти терміналів на вітрині.
• Агент трекінгу та сповіщення клієнтів про статуси.
• Документація та консультація щодо доробок.

Отримайте консультацію з інтеграції — наші інженери сертифіковані з Бітрікс та мають 5+ років комерційного досвіду. Зв'яжіться для оцінки вашого проєкту.

Терміни

Оцінимо ваш проєкт за 1 день — зв'яжіться, щоб обговорити деталі.