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