Інтеграція з службою доставки для США Shippo — live-доставка, етикетки та трекінг

Shippo (Lavvod) підключає ваш магазин OkayCMS до сервісу Shippo і забезпечує повний цикл роботи з доставкою: від вибору тарифу покупцем до створення етикетки, оформлення повернення та відстеження посилки.

Що отримує магазин

• Живі тарифи на чекауті — клієнт вводить адресу, модуль запитує Shippo та показує доступні служби й тарифи з актуальними цінами.
• Структурована адреса доставки — вулиця, квартира/офіс, місто, регіон, індекс і країна. Зручно для відправлень у США, Канаду та інші країни.
• Опційне автодоповнення адреси через Google Places — використовується окремий браузерний ключ Maps JavaScript API.
• Купівля PDF-етикетки безпосередньо з картки замовлення в адмінці. Також можна ввімкнути автоматичну купівлю етикетки при переході замовлення в обраний статус.
• Return label — створення зворотної етикетки та QR-коду, якщо вони повертаються Shippo.
• Трекінг відправлення через webhook Shippo з резервним cron-опитуванням OkayCMS.
• Габарити варіантів у дюймах (length_in / width_in / height_in) у картці товару, імпорті та експорті.
• Мови інтерфейсу модуля: українська, російська та англійська.

Як це працює

1. Створіть спосіб доставки та прив’яжіть до нього модуль Shippo.
2. У розділі Shippo → Налаштування вкажіть API-токен і адресу складу.
3. У кошику при виборі доставки Shippo з’являться поля адреси та список доступних тарифів.
4. Після оплати або підтвердження замовлення придбайте етикетку в адмінці — вручну або автоматично.
5. Статус відправлення оновлюватиметься через webhook та/або планувальник.

Важливо перед встановленням

• Вага варіантів у OkayCMS має бути в кілограмах — модуль автоматично конвертує її в lb для Shippo.
• Габарити товарів вказуються в дюймах.
• Підтримується одна сумарна посилка на замовлення — без multi-parcel.
• Рекомендована тема вітрини — стандартна okay_shop. Для кастомної теми необхідно підключити відповідні design-блоки згідно з інструкцією модуля.
• Після встановлення відкрийте Shippo → Встановлення — там знаходиться короткий чеклист інтеграції.

Можливості

• Live-тарифи Shippo в кошику (AJAX)
• Структурована адреса доставки + опційний street2
• Автодоповнення адреси через Google Places
• Збереження вибраного тарифу та адреси в замовленні
• Купівля outbound-етикетки з адмінки
• Автоматична купівля етикетки при зміні статусу замовлення
• Return label / QR
• Трекінг: webhook + cron fallback
• Габарити варіантів у дюймах у товарі, імпорті та експорті
• Фільтр перевізників і service levels
• Інструкція зі встановлення в адмінці
• Інтерфейс UA / RU / EN

Де з’являються зміни

На сайті

Кошик / оформлення замовлення

При виборі доставки Shippo з’являється блок адреси, список live-тарифів та автоматичне оновлення вартості доставки. Блок підключається через front_cart_delivery — у стандартній темі okay_shop він уже є в cart_deliveries.tpl.

Сторінка успішного замовлення (order.tpl)

Відображається блок адреси Shippo (lavvod_order_shippo_address). Він може бути доданий через TplMod із module.json або вручну.

Email клієнту про замовлення

Може відображатися адреса Shippo та/або інформація про трекінг. Використовуються блоки front_lavvod_email_order_shippo_address і front_email_order_user_contact_info. Для кастомної теми може знадобитися виклик get_design_block.

Без прив’язки способу доставки до модуля Shippo жодних додаткових елементів на вітрині не з’являється.

В адмінці

Shippo → Налаштування Shippo
API-токен, адреса складу, посилка за замовчуванням, стратегія тарифу, перевізники та сервіси, webhook, авто-етикетка, Google Places.

Налаштування → Доставки
Модуль Shippo можна прив’язати до потрібного способу доставки.

Замовлення → картка замовлення
Блок Shippo з адресою, котируваннями тарифів, купівлею етикетки, поверненням і трекінгом. Після придбання етикетки спосіб доставки блокується.

Каталог → товар → варіанти
Додаються поля габаритів Д×Ш×В у дюймах.

Налаштування → Імпорт
Додаткові поля зіставлення length_in / width_in / height_in.

Експорт товарів
Додаються колонки з габаритами Shippo.

Друк замовлення
Можна відображати адресу Shippo, якщо в шаблоні друку підключений lavvod_order_print_shippo_address.

Email адміністратору про замовлення
Можна додати адресу та інформацію про трекінг Shippo через backend-блоки.

Ролі менеджерів
Дозвіл lavvod__shippo керує доступом до розділу Shippo.

Що модуль автоматично не змінює

Файли кастомної теми не перезаписуються автоматично, окрім TplMod для order.tpl, якщо відповідний механізм увімкнено.

Для email, друку замовлення та кастомної теми необхідні блоки додаються відповідно до інструкції в Shippo → Встановлення / INSTALL.md.