Інтеграція 1С-Бітрікс зі службою доставки Казпошта (Казахстан)

Ситуація: клієнт втрачав до 30% замовлень через непрацюючу доставку в регіони Казахстану

До нас звернувся інтернет-магазин з товарообігом 5 млн тенге на місяць. Приватні кур'єри доставляли тільки в Алмати та Астану, в районні центри — тільки Казпошта. Вбудований модуль Бітрікса не справлявся: розрахунок вартості видавав помилки, трекінг був відсутній. Ручне виписування накладних займало 2 години на день, а помилки в індексах призводили до повернень. Ми провели аудит і вирішили повністю переписати обробник доставки через REST API Казпошти. Економія на ручній обробці замовлень склала 15 годин на місяць. В результаті після впровадження клієнт автоматизував 90% замовлень, час обробки скоротився з 30 хвилин до 2 хвилин на замовлення. Крім того, ми усунули помилки округлення вартості, які виникали через невірну конвертацію валют. Тепер покупці з будь-якого міста Казахстану можуть оформити доставку онлайн, а магазин отримує актуальну вартість з урахуванням ваги та оголошеної цінності.

Як працює інтеграція з Казпоштою?

Казпошта — державний оператор з 3500+ відділень. API доступний партнерам після договору. Базовий URL: https://api.kazpost.kz/api/v1. Авторизація через X-Api-Key. Основні методи:

• POST /delivery/calculate — розрахунок вартості
• POST /shipment/create — створення відправлення
• GET /shipment/{barcode}/track — трекінг
• GET /offices — список відділень за індексом

Докладніше про REST API — архітектуру, на якій побудований сервіс.

Розрахунок вартості

class KazposhtaHandler extends \Bitrix\Sale\Delivery\Services\Base { protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $toIndex = $this->getPostIndex($shipment); if (!$toIndex) { $result->addError(new \Bitrix\Main\Error('Не указан почтовый индекс получателя')); return $result; } $response = $this->apiPost('/delivery/calculate', [ 'from_index' => $this->getOption('SENDER_INDEX'), 'to_index' => $toIndex, 'weight' => max((int)$shipment->getWeight(), 100), 'declared_value' => round($shipment->getOrder()->getPrice()), 'mail_type' => 'PARCEL', 'mail_class' => 'ORDINARY', ]); if (!empty($response['total_rate'])) { $result->setDeliveryPrice((float)$response['total_rate']); $min = $response['delivery_days_min'] ?? 3; $max = $response['delivery_days_max'] ?? 14; $result->setPeriodDescription("{$min}–{$max} дней"); } return $result; } private function getPostIndex(\Bitrix\Sale\Shipment $shipment): ?string { $props = $shipment->getOrder()->getPropertyCollection(); $index = $props->getItemByOrderPropertyCode('ZIP')?->getValue(); return preg_match('/^\d{6}$/', (string)$index) ? $index : null; } } 

Поштовий індекс — обов'язкове поле. У формі оформлення замовлення робимо його обов'язковим і валідуємо формат (6 цифр).

Як налаштувати обробник доставки?

1. Встановіть модуль доставки Казпошти або створіть свій клас, успадкований від \Bitrix\Sale\Delivery\Services\Base.
2. Зареєструйте обробник в адміністративній панелі Бітрікса: налаштування → служби доставки → додати.
3. Додайте властивості замовлення: ZIP (індекс), ADDRESS, FIO, PHONE. Для трекінгу — користувацьку властивість UF_KAZPOST_BARCODE.
4. Реалізуйте методи calculateConcrete та createShipment, як показано вище.
5. Налаштуйте агент для періодичного опитування статусів.

Створення відправлення

public function createShipment(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $response = $this->apiPost('/shipment/create', [ 'sender' => [ 'index' => $this->getOption('SENDER_INDEX'), 'address' => $this->getOption('SENDER_ADDRESS'), 'name' => $this->getOption('SENDER_NAME'), 'phone' => $this->getOption('SENDER_PHONE'), ], 'recipient' => [ 'index' => $props->getItemByOrderPropertyCode('ZIP')?->getValue(), 'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), ], 'parcel' => [ 'weight' => max((int)$shipment->getWeight(), 100), 'declared_value' => round($order->getPrice()), 'mail_type' => 'PARCEL', 'description' => 'Товар', ], 'payment_type' => 'PREPAID', ]); return $response['barcode'] ?? ''; } 

Штрих-код відправлення зберігаємо в UF_KAZPOST_BARCODE.

Чому агент обов'язковий для трекінгу?

API Казпошти не надсилає вебхуки — статуси потрібно опитувати. Заводимо агент Бітрікс, що запускається раз на 6 годин. Він перевіряє штрих-коди замовлень у статусі "P" (оплачено) і при статусі "DELIVERED" переводить замовлення в "F" (доставлено). Важливо передбачити timeout для API запитів (рекомендуємо 10–15 сек) і логування помилок, щоб при збої Казпошти агент не зависав. Механізм повторів при помилці 500–503 допомагає уникнути втрати статусів.

function checkKazposhtaStatus(): string { $orders = \Bitrix\Sale\Order::getList([ 'filter' => ['=PROPERTY_VAL.UF_KAZPOST_BARCODE' => true, '=STATUS_ID' => 'P'], 'select' => ['ID'] ]); foreach ($orders as $order) { $barcode = $order->getPropertyCollection()->getItemByOrderPropertyCode('UF_KAZPOST_BARCODE')->getValue(); $track = new KazposhtaHandler()->track($barcode); if ($track['status'] === 'DELIVERED') { $order->setField('STATUS_ID', 'F'); $order->save(); } } return 'checkKazposhtaStatus();'; } 

При помилках API (наприклад, 400 з тілом {"error": "Invalid index"}) обробник виводить повідомлення: "Поштовий індекс отримувача вказано невірно". Всі запити логуються в /bitrix/logs/kazpost.log для налагодження.

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

• Невірний формат індексу — має бути 6 цифр. Валідуйте на клієнті через маску введення і на сервері через preg_match('/^\d{6}$/'). При помилці виводьте повідомлення "Перевірте поштовий індекс отримувача".
• Відсутність обов'язкових властивостей замовлення (ZIP, ADDRESS, FIO, PHONE) — запобігти пустим даним обов'язковими полями у формі оформлення. Перед запитом до API виконуйте перевірку через isset() і !empty().
• Не налаштовано агент для трекінгу — статуси не оновлюються. Переконайтеся, що агент зареєстровано в адмінці та запускається за розкладом (cron). Перевірте логи в /bitrix/logs/ при відсутності оновлень.
• Некорректний API-ключ — повертає 401. Перевірте наявність ключа в змінних оточення та термін його дії у партнера Казпошти (ключі вимагають періодичного оновлення контракту).

Особливості доставки Казпоштою

• Адресна доставка до дверей — тільки у великих містах (Алмати, Астана, Шимкент), в інших — до відділення.
• EMS — швидше та надійніше для термінових відправлень у великі міста.
• API Казпошти підтримує післяплату (COD), комісія ~2% від суми.
• Тариф розраховується в тенге — перевірте налаштування валюти магазину.

Терміни та етапи робіт

Що входить в роботу

• Розробка класу-обробника доставки (на базі \Bitrix\Sale\Delivery\Services\Base).
• Налаштування властивостей замовлення: індекс, адреса, штрих-код.
• Створення агента для трекінгу.
• Інтеграція з фіскалізацією (54-ФЗ) — обговорюється окремо.
• Тестування на тестовому та бойовому контурах.
• Передача документації та доступів.

Вартість інтеграції розраховується індивідуально і зазвичай становить від 80 000 до 150 000 тенге. Ми гарантуємо стабільну роботу. Досвід — 5+ років, більше 20 проектів з інтеграції 1С-Бітрікс з поштовими службами. На запит надаємо сертифікати партнера 1С-Бітрікс.

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