Интеграция со службой доставки для США 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
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.