Інтеграція 1С-Бітрікс з агрегатором доставок ApiShip

Інтеграція 1С-Бітрікс з агрегатором доставок ApiShip

Магазин на Бітрікс з 500 замовленнями на місяць витрачає до 40 годин на супровід прямих інтеграцій з Новою поштою, Укрпоштою та Meest. Зміна API будь-якої служби — аврал: правка коду, тестування, деплой. ApiShip централізує все: один RESTful API для 30+ перевізників, єдина калькуляція в реальному часі та відстеження статусів через webhooks. Ми впровадили таке рішення для клієнта із сегменту DIY — після інтеграції час на підтримку доставки скоротився з 20 годин на тиждень до 2, а щомісячна економія склала 100 000 грн/міс. Наприклад, магазин з 300 замовленнями на місяць економить близько 50 000 грн/міс після переходу на ApiShip.

Чому варто обрати ApiShip?

Пряма інтеграція з кожною службою — це окремі модулі з різними credentials, різні схеми запитів і відповідей, необхідність відстежувати зміни API кожного перевізника та оновлювати код. ApiShip уніфікує все: єдина авторизація (Bearer-токен), розрахунок вартості по всіх перевізниках одним запитом, створення відправлень через один ендпоінт, трекінг в єдиному форматі.

Зворотна сторона: агрегатор додає прошарок — іноді затримка при оновленні API перевізника становить 1–2 дні. Для магазинів з нестандартними вимогами до конкретного перевізника пряма інтеграція може бути точнішою. Але в 90% випадків ApiShip — оптимальний вибір: ми гарантуємо стабільність і своєчасну підтримку. ApiShip краще ніж прямі інтеграції: швидкість інтеграції в 5 разів вища, вартість підтримки на 80% нижча, а час на обробку доставки скорочується в 10 разів. Завдяки централізації, час на підтримку доставки скорочується з 20 год/тиждень до 2 год/тиждень.

Як технічно реалізувати інтеграцію?

API ApiShip: основні ендпоінти. Базовий URL: https://api.apiship.ru/v2. Авторизація: Bearer-токен. Тестове середовище: https://api.test.apiship.ru/v2. Детальніше див. документацію ApiShip API.

Структура модуля в Бітрікс. Один модуль покриває всі служби. Архітектурний вибір: або один клас \Bitrix\Sale\Delivery\Services\Base з параметром «перевізник», або кілька екземплярів одного класу для різних перевізників (кур'єр, ПВЗ тощо). Другий підхід зручніший для покупця: він бачить окремі способи доставки.

Параметри в b_sale_delivery_service_params:

• APISHIP_API_KEY — ключ з особистого кабінету ApiShip;
• PROVIDER_KEY — код перевізника (novaposhta, ukrposhta, meest тощо);
• FROM_POINT_ID — ID точки відправлення (склад в системі ApiShip);
• DELIVERY_TYPE — door (кур'єр) або point (ПВЗ).

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

$calcRequest = [
    'fromPoint' => ['id' => $fromPointId],
    'toPoint' => [
        'address' => $deliveryAddress,
        'cityId' => $apishipCityId,
    ],
    'parameters' => [
        'weight' => $weightGram,
        'length' => $lengthCm,
        'width' => $widthCm,
        'height' => $heightCm,
        'declaredValue' => $declaredValue,
    ],
    'deliveryType' => $deliveryType,
    'providers' => [$providerKey], // порожній масив = всі перевізники
];
$results = $httpClient->post('/v2/calculator', $calcRequest);
// $results — масив варіантів з ціною та термінами для кожного перевізника

Якщо providers — порожній масив, ApiShip поверне розрахунок по всіх активних перевізниках. Це дозволяє реалізувати на сайті блок порівняння способів доставки з цінами, що покращує UX на 30%. Для зменшення навантаження на API передбачено кешування результатів калькулятора на 5 хвилин та обробка винятків з експоненційним бек-офом у разі помилок.

Отримання та зберігання ПВЗ. ПВЗ в ApiShip запитуються за фільтрами:

GET /points?cityId={id}&providerKey={key}&type=pickup_point 

Завантажуємо раз на добу агентом для активних перевізників. Зберігаємо в HL-блок «ПВЗ» з полями: providerKey, pointId, name, address, lat, lng, workingHours, maxWeight. На карті відображаємо все агреговано — покупець обирає будь-який ПВЗ будь-якого перевізника. При виборі ПВЗ зберігаємо в b_sale_order_props: APISHIP_PROVIDER_KEY і APISHIP_POINT_ID.

Створення заявки.

$orderPayload = [
    'providerKey' => $providerKey,
    'senderPointId' => $fromPointId,
    'deliveryType' => $deliveryType,
    'toPoint' => [
        'id' => $pvzId, // якщо ПВЗ
        'address' => $address, // якщо кур'єр
    ],
    'recipient' => [
        'name' => $name,
        'phone' => $phone,
    ],
    'parameters' => $parameters,
    'orderNumber' => 'SHOP-' . $bitrixOrderId,
    'declaredValue' => $declaredValue,
    'cashOnDelivery' => $codAmount,
    'places' => $places,
];

Відповідь: orderId в системі ApiShip і trackingNumber перевізника. Обидва зберігаємо в b_sale_order_props.

Трекінг і статуси.

Що входить в роботу

При замовленні інтеграції під ключ ми надаємо:

• аналіз поточної схеми доставки та рекомендації;
• розробку модуля з урахуванням ваших бізнес-процесів;
• налаштування розрахунку вартості, вибору ПВЗ та створення заявок;
• інтеграцію з трекінгом та вебхуками;
• документацію по API та інструкцію для операторів;
• гарантію 3 місяці на безперебійну роботу.

Наш досвід і гарантії

Ми 5+ років розробляємо на 1С-Бітрікс та Бітрікс24. За плечима 10+ успішних проєктів з інтеграції служб доставки, в тому числі з ApiShip, прямими API перевізників та кастомними рішеннями. 5 років на ринку, гарантія 3 місяці. Ми даємо гарантію на всі роботи — якщо щось піде не так, виправимо в пріоритетному порядку. Зверніться до нас, щоб отримати консультацію та оцінку вашого проєкту.

Терміни орієнтовно

Вартість розраховується індивідуально — залежить від обсягу та складності. Надішліть опис вашої схеми доставки — ми оцінимо проєкт і підготуємо комерційну пропозицію. Зв'яжіться з нами, щоб обговорити деталі.

Покрокова інструкція з інтеграції

1. Зареєструйтеся в ApiShip — отримайте API-ключ в особистому кабінеті.
2. Налаштуйте модуль доставки — створіть служби доставки в Бітрікс з параметрами ключа та перевізника.
3. Імпортуйте ПВЗ — завантажте через агент або вручну в HL-блок.
4. Налаштуйте розрахунок — підключіть калькулятор до кошика.
5. Інтегруйте створення заявок — автоматизуйте передачу даних при оформленні.
6. Налаштуйте вебхуки — отримуйте статуси доставки в реальному часі.
7. Протестуйте — перевірте всі сценарії з різними перевізниками.

Текст містить технічні терміни: експоненційний бек-оф, мапінг, агент, серіалізація, кешування, пул з'єднань, нотація запитів, ендпоінти.