Інтеграція 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С-Бітрікс вирішує цю проблему: ми підключаємо служби доставки так, щоб ціна показувалася миттєво, а трекінг оновлювався без участі менеджера. Більше 50 реалізованих проєктів з каталогами від 500 до 100 000 SKU, досвід понад 8 років. Середній час підключення однієї транспортної компанії — 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 простіше, ніж у СДЕК, але є нюанси з післяплатою та частковим викупом. Типові помилки при інтеграції: відсутність фільтрації ПВЗ за ознакою onlyPrepaid → помилки при післяплаті; ігнорування параметра partialReturn → ламає частковий викуп. API повертає код міста у форматі "770000000000" — потрібне маппінг на index міста.

Нова пошта — лідер українського ринку

Для України — обов'язкове підключення Нової пошти через API v2. Розрахунок вартості, створення ЕН, друк накладної, трекінг. Карта відділень з фільтрацією (поштомати, прийом платежів). Асинхронне оновлення статусів через агент Бітрікс кожні 15 хвилин.

ПЕК — важкі вантажі та збір

Коли потрібно відправити диван або обладнання. Розрахунок збірних вантажів, страхування, обрешітка. Доставка до терміналу та від дверей до дверей. Індекси терміналів ПЕК підвантажуємо в інфоблок для автопідстановки.

DPD — експрес-доставка з часовими слотами

DPD по Україні та за кордон. Доставка у вибраний часовий інтервал, повернення підписаних документів. У розрахунку враховуємо об'ємну вагу за формулою (Д×Ш×В)/4000 — відмінність від СДЕК. Документація DPD: volumetric weight factor 4000.

Як об'єднати різні ТК в єдиному калькуляторі?

Використовуємо гібридний підхід: модуль-агрегатор, який маршрутизує запити до різних API та нормалізує відповіді. Він обробляє запити в 5 разів швидше, ніж окремі інтеграції, завдяки паралельним викликам через curl_multi. У відповіді модуля — єдина структура: назва тарифу, ціна, термін, тип доставки. Кешування теговане: при зміні налаштувань модуля очищується лише кеш розрахунку для обраного міста, решта залишається. Подію 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 місяць) — виправлення багів, коригування конфігурацій, доналаштування кешування.

Що входить у вартість інтеграції

• Документація зі схемою обміну (логістичні маршрути, тарифні зони).
• Налаштовані доступы до API кожної ТК, ключі, вебхуки.
• Шаблони повідомлень (email, SMS, push) для статусів доставки.
• Навчання менеджерів: робота з адмінкою, друк документів, обробка помилок.
• Півроку технічної підтримки після запуску.

Орієнтовні терміни реалізації

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

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