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

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

Казпочта — государственный почтовый оператор Казахстана с отделениями в 3500+ населённых пунктах. Актуальна при доставке в регионы, где частные курьерские службы не работают. API предоставляется партнёрам после заключения договора.

API Казпочты

Базовый URL REST API: https://api.kazpost.kz/api/v1. Авторизация через API-ключ в заголовке X-Api-Key. Основные методы:

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

Расчёт стоимости

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();
        // Казахстанский индекс — 6 цифр
        return preg_match('/^\d{6}$/', (string)$index) ? $index : null;
    }
}

Почтовый индекс — обязательное поле. При выборе Казпочты в форме оформления заказа нужно сделать его обязательным и добавить валидацию формата (6 цифр).

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

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.

Трекинг и особенности

public function track(string $barcode): array
{
    return $this->apiGet("/shipment/{$barcode}/track") ?? [];
}

Агент Битрикс проверяет статус раз в 6 часов. Особенности работы с Казпочтой:

• Адресная доставка до двери — только в крупных городах (Алматы, Астана, Шымкент), в остальных случаях доставка до отделения
• EMS — быстрее и надёжнее, актуален для срочных отправлений в крупные города
• COD (наложенный платёж) поддерживается, комиссия ~2% от суммы
• Тариф рассчитывается в казахстанских тенге — убедитесь в правильной настройке валюты магазина

Сроки