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

Интеграция доставки: от разрозненных API к единому калькулятору за 5 дней

Покупатель бросает корзину на этапе доставки — не видит расчёта или видит заведомо неверную цену. Каждый такой случай теряет конверсию. Автоматизация логистики в 1С-Битрикс решает эту проблему: мы подключаем службы доставки так, чтобы цена показывалась мгновенно, а трекинг обновлялся без участия менеджера. За 8 лет реализовано более 50 проектов с каталогами от 500 до 100 000 SKU. Среднее время подключения одной транспортной компании — 4 дня.

Как ускорить подключение служб доставки к 1С-Битрикс?

Главная сложность — не сам вызов API, а адаптация к логике каждого перевозчика. СДЭК, Boxberry, Почта России, ПЭК, DPD — у каждого свой формат запроса, тарификация и обработка ошибок. Мы используем готовые адаптеры под каждую ТК, что сокращает время интеграции втрое по сравнению с реализацией с нуля. Развернутый кейс: интернет-магазин товаров для дома (15 000 товаров) — подключили СДЭК и Boxberry за 5 дней, автоматизировали расчёт и создание заказов. Обращения в поддержку по доставке снизились на 60%, средний чек вырос на 8% за счёт индикатора бесплатной доставки.

Почему API каждой транспортной компании — отдельный квест?

СДЭК — объёмный вес и карта ПВЗ

API v2 (/api/v2/calculator/tarifflist) принимает габариты, вес и адреса — возвращает все доступные тарифы. Подводные камни: объёмный вес рассчитывается по формуле (Д × Ш × В) / 5000. Если физический вес 2 кг, а объёмный 8 кг — СДЭК берёт по объёмному. Не учтёте в калькуляторе — покупатель увидит одну цену, а заплатит другую. Карта ПВЗ загружается через /deliverypoints. Виджет СДЭК можно встроить, но он конфликтует со стилями Битрикс — рисуем свою карту на Яндекс.Картах. Автоматическое создание заказа через /api/v2/orders — при оформлении заявка улетает в СДЭК, возвращается трек-номер. Печать накладных и этикеток из админки — через /api/v2/print/orders. Тарифы: склад-склад, склад-дверь, дверь-дверь, экспресс, постамат.

Boxberry — широкая сеть ПВЗ в регионах

Самая широкая сеть пунктов выдачи в малых городах. API проще, чем у СДЭК, но есть нюансы с наложенным платежом и частичным выкупом. Карта ПВЗ с фильтрацией: примерка, оплата картой, работа в выходные. Обязательно проверяем корректную обработку ответа 0 при отсутствии ПВЗ.

Почта России — стабильность ценой скорости

API «Отправка» — расчёт стоимости, автоформирование бланков ф.103 и ф.116, трекинг по трек-номеру. Тарифы: посылка, бандероль, EMS. Международные отправления. API медленнее коммерческих ТК — закладываем таймауты 10 секунд, используем асинхронные агенты Битрикс для обновления статусов.

ПЭК — тяжёлые грузы и сбор

Когда нужно отправить диван или оборудование. Расчёт сборных грузов, страхование, обрешётка. Доставка до терминала и от двери до двери. Индексы терминалов ПЭК подгружаем в инфоблок для автоподстановки.

DPD — экспресс-доставка с временными слотами

DPD по России и за рубеж. Доставка в выбранный временной интервал, возврат подписанных документов. В расчёте учитываем объёмный вес по формуле (Д×Ш×В)/4000 — отличие от СДЭК.

Как объединить разные ТК в едином калькуляторе?

Используем гибридный подход: модуль-агрегатор, который маршрутизирует запросы к разным API и нормализует ответы. Это позволяет сравнивать тарифы в реальном времени без переключения между личными кабинетами. В ответе модуля — единая структура: название тарифа, цена, срок, тип доставки. Кэширование тегированное: при изменении настроек модуля очищается только кэш расчёта для выбранного города, остальное остаётся. Событие OnBeforeDeliveryCalculate вешаем на кастомный обработчик — так подменяем стандартную логику доставки.

Расчёт стоимости: какие грабли встречаются?

Автоматический калькулятор суммирует физический и объёмный вес товаров в корзине, прибавляет вес упаковки, выбирает наибольший. Звучит просто, но:

• Габариты должны быть заполнены у каждого товара. Нет габаритов — нет расчёта. На каталоге в 10 000 SKU обязательно найдутся товары без размеров — для них заводим дефолтные значения (например, 0.1×0.1×0.1 м) и предупреждаем менеджера через почтовое событие.
• Промоакции и пороги бесплатной доставки — гибкая настройка: по сумме заказа, для VIP-клиентов, при конкретном способе оплаты. Реализуем через пользовательские свойства корзины.
• Индикатор «До бесплатной доставки осталось N руб.» — простая штука, но поднимает средний чек на 5–12%. Вычисляем по сумме корзины и ближайшему порогу, выводим в шаблоне корзины.

Как автоматизировать трекинг, самовывоз и курьерскую доставку?

Трекинг. Автоматический опрос API транспортных компаний — агент Битрикс каждые 30 минут проверяет статусы заказов, у которых STATUS_DELIVERY != 'DELIVERED'. При изменении — обновление статуса заказа в системе и уведомление покупателю (email, SMS, push). Встроенная страница трекинга в личном кабинете — покупателю не нужно идти на сайт ТК. Карта с текущим местоположением, прогнозируемая дата доставки, возможность переадресации.

Самовывоз. Собственные точки выдачи на карте: адреса, график, контакты. Поиск ближайшей по адресу покупателя. Проверка наличия в реальном времени, бронирование до определённого часа. QR-код для быстрого получения и SMS о готовности к выдаче.

Курьерская доставка. Зоны доставки с разной стоимостью. 2-часовые слоты, управление расписанием курьеров, ограничение заказов на слот. Доставка день в день — приём до 14:00, экспресс за 2-4 часа с наценкой за срочность. Интеграция с навигацией для оптимизации маршрутов.

Мультисклад. Несколько складов с адресами и зонами обслуживания. Автоматический выбор склада отгрузки по адресу покупателя — приоритет ближайшему, где есть все товары заказа. Если на одном складе всего нет — разделение заказа по складам (мультидоставка). Синхронизация остатков через 1С или WMS (CommerceML), используем события OnBeforeBasketAdd для проверки доступности.

Сравнение транспортных компаний

Из каких этапов состоит подключение служб доставки?

1. Анализ логистики (1–2 дня) — география, средний вес, объём заказов, интеграция с 1С. Рекомендуем комбинацию ТК.
2. Подключение API (3–5 дней на ТК) — настройка расчётов, карт ПВЗ, автоматическое создание заказов через агенты и события.
3. Настройка трекинга (1–2 недели) — агенты обновления статусов, шаблоны уведомлений, страница трекинга.
4. Тестирование (2–3 дня) — проверка на реальных адресах, сравнение тарифов, контроль ошибочных расчётов, нагрузочное тестирование.
5. Деплой и обучение (1 день) — выгрузка модуля, передача доступов, обучение менеджеров.
6. Гарантийная поддержка (1 месяц) — исправление багов, корректировка конфигураций, донастройка кэширования.

Ориентировочные сроки реализации

Сроки зависят от количества ТК, сложности каталога и необходимости интеграции с 1С/ERP. Стоимость рассчитывается индивидуально — ориентируйтесь на экономию: снижение операционных затрат на доставку до 40% и сокращение обращений в поддержку на 60%. Например, один из клиентов с магазином электроники (20 000 товаров) вернул инвестиции за 3 месяца за счёт уменьшения числа «забытых» заказов.

Готовы ускорить логистику вашего интернет-магазина? Свяжитесь с нами — поможем подобрать оптимальную комбинацию ТК под ваш ассортимент и бюджет. Закажите консультацию, и мы подготовим предложение за 1 рабочий день.