Інтеграція 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. Протестуйте — перевірте всі сценарії з різними перевізниками.

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