Интеграция 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 день и подготовим предложение. Закажите расчёт по почте или через форму обратной связи.