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

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

Казпошта — національний поштовий оператор Казахстану. Покриття — всі населені пункти країни, включаючи важкодоступні райони. Для e-commerce, що працює на казахстанський ринок, Казпошта необхідна там, де приватні кур'єрські служби не працюють. API надає REST-інтерфейс з токен-авторизацією.

API Казпошти: підключення

Казпошта надає API через партнерський кабінет. Базовий URL продакшн-середовища: https://api.kazpost.kz/api/v1/. Авторизація через API-ключ у заголовку Authorization: Bearer TOKEN.

private function apiRequest(string $method, string $path, array $data = []): array
{
    $url = 'https://api.kazpost.kz/api/v1' . $path;
    $ch = curl_init($method === 'GET' ? $url . '?' . http_build_query($data) : $url);

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $this->getOption('API_TOKEN'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => $method !== 'GET' ? json_encode($data) : null,
    ]);

    $response = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code >= 400) {
        throw new \RuntimeException("Kazpost API error {$code}: {$response}");
    }

    return json_decode($response, true) ?? [];
}

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

public function calcPrice(
    string $fromZip,
    string $toZip,
    int $weightGram,
    string $mailType = 'SMALL_PACKAGE'
): float {
    $response = $this->apiRequest('POST', '/tariff/calculate', [
        'fromZip'     => $fromZip,
        'toZip'       => $toZip,
        'weight'      => $weightGram,
        'mailType'    => $mailType, // SMALL_PACKAGE, PACKAGE, EMS
        'addServices' => [],
    ]);

    return (float)($response['totalCost'] ?? 0);
}

Типи відправлень: SMALL_PACKAGE (малий пакет, до 2 кг), PACKAGE (посилка), EMS (експрес). Вартість розраховується в тенге.

Пошук індексу за адресою

Для розрахунку потрібен поштовий індекс отримувача. Казпошта надає API пошуку індексу:

public function findZipByAddress(string $city, string $street, string $house): ?string
{
    $cacheKey = 'kazpost_zip_' . md5($city . $street . $house);
    $cached = \Bitrix\Main\Data\Cache::createInstance();

    if ($cached->startDataCache(86400 * 7, $cacheKey, '/kazpost')) {
        $response = $this->apiRequest('GET', '/address/search', [
            'city'   => $city,
            'street' => $street,
            'house'  => $house,
        ]);
        $zip = $response[0]['zip'] ?? null;
        $cached->endDataCache(['zip' => $zip]);
    }

    return $cached->getVars()['zip'];
}

На сайті поле «Поштовий індекс» можна заповнювати автоматично: покупець вводить адресу, AJAX-запит визначає індекс. Кешуємо на тиждень — індекси змінюються рідко.

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

public function createMailItem(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    $payload = [
        'mailType'       => 'PACKAGE',
        'weight'         => $this->getWeight($shipment),
        'declaredValue'  => (int)($order->getPrice() * 100), // в тиїнах
        'cashOnDelivery' => 0,
        'sender' => [
            'name'    => $this->getOption('SENDER_NAME'),
            'zip'     => $this->getOption('SENDER_ZIP'),
            'address' => $this->getOption('SENDER_ADDRESS'),
            'phone'   => $this->getOption('SENDER_PHONE'),
        ],
        'recipient' => [
            'name'    => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'zip'     => $props->getItemByOrderPropertyCode('KAZPOST_ZIP')?->getValue(),
            'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'phone'   => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        ],
        'items' => $this->buildItems($order),
    ];

    $response = $this->apiRequest('POST', '/mail-items', $payload);
    $barcode = $response['barcode'] ?? '';

    $props->getItemByOrderPropertyCode('KAZPOST_BARCODE')?->setValue($barcode);
    $order->save();

    return $barcode;
}

Оголошена цінність (declaredValue) передається в тиїнах (1 тенге = 100 тиїнів). Це типова особливість казахстанських API — враховуйте конвертацію.

Трекінг

public function track(string $barcode): array
{
    $response = $this->apiRequest('GET', '/tracking/' . $barcode);
    $events = $response['events'] ?? [];
    $last = end($events);

    return [
        'status'   => $last['statusName'] ?? '',
        'date'     => $last['eventDate'] ?? '',
        'location' => $last['locationName'] ?? '',
    ];
}

Терміни