Qapla’ для OpenCart — пункты выдачи, этикетки и трекинг перевозчиков (Италия)

Shipping with Qapla’ for OpenCart (OpenCart 4.x, 3.x и 2.3) подключает магазин к Qapla’, итальянской платформе отправлений и трекинга. Покупатель на кассе выбирает пункт выдачи (punto di ritiro) курьера, а заказ одной кнопкой попадает в Qapla’ с получателем, посылкой, товарами и выбранным пунктом. В Pro добавляются этикетки, автоматика по статусам, трекинг в заказе и письмо покупателю с номером отслеживания.

Что нужно от Qapla’. Канал Qapla’ с приватным API-ключом (панель Qapla’ → Settings → Channels → ваш канал → Configure → Channel → Private API Key). Доступ к API зависит от вашего тарифа Qapla’, а поиск пунктов выдачи включает по запросу поддержка Qapla’. Тарифы Qapla’ оплачиваются отдельно. Ключ хранится зашифрованным и обратно на странице не показывается.

Что получает покупатель

На кассе (штатной и CatCode One Page Checkout) появляются методы доставки, которые вы настроили: курьер вашего канала, на адрес или в пункт выдачи. Для метода «в пункт» под ним открывается панель: покупатель видит пункты по почтовому индексу (CAP) своего адреса, может ввести другой CAP или город, и видит название, адрес, расстояние и часы работы. Без выбранного пункта заказ оформить нельзя: это проверяет сервер, а не только страница.

Адрес доставки заказа становится адресом пункта: так он идёт в админку, счёт и письма. Пункт курьера PTI (Poste Italiane) не принимает наложенный платёж, и такая комбинация отклоняется с пояснением. Пункт принимается только из собственного поиска сервера, придуманный идентификатор отклоняется. Результаты поиска кэшируются на 6 часов, а поисков на сессию — 20 за 10 минут, чтобы не упираться в лимит Qapla’ — 150 обращений в минуту на канал. Интерфейс покупателя итальянский, когда магазин на итальянском, иначе английский.

Что получает админ

Extensions → Extensions → Shipping → Shipping with Qapla’: шесть вкладок: «Delivery methods», «Qapla’ account», «Orders», «Labels and tracking», «Journal» и «Licence». На «Qapla’ account» вы вставляете API-ключ и нажимаете «Save and check the connection»: модуль показывает название канала и подключённых курьеров (например BRT, GLS, Poste Italiane), и страница перезагружается со списками для настройки методов. Блок «Try it» ищет пункты по курьеру, стране и CAP, так что видно, что увидит покупатель; если Qapla’ ответил ошибкой, её текст виден на месте.

На «Delivery methods» вы настраиваете до восьми методов: курьер канала (с вариантами контрактов, как BRT-V1), на адрес или в пункт выдачи, название, цена (фиксированная), бесплатно от суммы, максимальный вес, страны, геозона и налоговый класс. Кнопка «Qapla’ orders» ведёт в список заказов Qapla’ с фильтрами «Not sent to Qapla’», «Without a label» и «On the way».

В заказе появляется панель «Qapla’»: курьер, выбранный пункт, кнопка «Send to Qapla’» (получатель, провинция, сумма, наложенный платёж, товары с артикулами, вес и размер, пункт). Повторная отправка обновляет заказ в Qapla’. Заказ с другим методом доставки уходит с курьером, которого вы выберете, или с курьером по умолчанию. Пункт можно найти и изменить в заказе, а текст отказа Qapla’ ложится в панели и в истории заказа одной строкой.

Что добавляет Pro

В Pro кнопка «Create label» создаёт отправление и этикетку из заказа: PDF, JPG или ZPL для скачивания, этикетка возврата и удаление этикетки (Delete label). Для заказа создаётся одна этикетка: двойной клик не дублирует её, а отправление в статусе ожидания модуль дочитывает позже. Тестовый режим («sandbox») создаёт этикетки без бронирования.

Автоматика: вы выбираете статусы заказа, на которых он отправляется в Qapla’ и на которых создаётся этикетка. Трекинг приходит из вебхука Qapla’ (его адрес показан на вкладке «Labels and tracking», а ключ канала проверяется в самом запросе) и из почасовой проверки; кнопка «Refresh tracking» обновляет вручную. Статус Qapla’ «доставлено» (99) переводит заказ в выбранный вами статус, а возвраты (95) добавляются строкой. Покупатель получает одно письмо с номером и ссылкой отслеживания.

В списке заказов Qapla’ доступны массовые действия: отправить в Qapla’ (до 100 заказов одним вызовом), создать этикетки (до 50), скачать все этикетки одним ZIP и обновить трекинг. Журнал показывает последние 300 обращений к Qapla’ и вебхуков. Также в Pro правила курьера для заказов с другими методами (по стране, весу и методу), цена по весу и доплата за наложенный платёж.

Как это работает, шаг за шагом

1. Установите архив для вашей версии OpenCart и установите модуль в Extensions → Extensions → Shipping.
2. В панели Qapla’ скопируйте приватный API-ключ канала.
3. На вкладке «Qapla’ account» вставьте ключ и нажмите «Save and check the connection»: появятся название канала и курьеры.
4. На вкладке «Delivery methods» добавьте методы: курьер, на адрес или в пункт выдачи, цена.
5. Оформите пробный заказ: на кассе выберите метод «в пункт» и пункт из списка.
6. Откройте заказ в админке и нажмите «Send to Qapla’», а дальше — в панели Qapla’.

Что под капотом

• Qapla’ API 1.3 и 1.2 (api.qapla.it): getChannel, getCouriers, getPudos, pushOrder, createLabel, getLabel, deleteLabel, getShipment, trackingByTimeFrame, вебхук Qapla’. Ключ канала шифруется, в логе и на страницах его нет.
• Пункты выдачи берутся из getPudos по CAP, а их часы работы складываются на языке покупателя (lun/mar/sab или Mon/Tue/Sat). Пункт, не пришедший из собственного поиска сервера, не принимается.
• Этикетка создаётся под блокировкой базы, поэтому двойной клик не создаёт два отправления; отправление в статусе PENDING не создаётся повторно.
• Для OpenCart 3 и 2.3 проверка трекинга идёт по адресу для cron, а для OpenCart 4 — через планировщик OpenCart; вебхук — отдельный адрес модуля.
• Настройки остаются после повторной установки модуля; при удалении таблицы истории и заказов Qapla’ не стираются.
• Интерфейс на английском и итальянском.

Как установить

1. Extensions → Installer: загрузите архив для вашей версии без переименования (OpenCart 4: cc_qapla.ocmod.zip, 3.x: cc_qapla-oc3.ocmod.zip, 2.3: cc_qapla-oc23.ocmod.zip; для 2.3 скопируйте содержимое upload/ в корень магазина).
2. Для 3.x и 2.3: Extensions → Modifications → Refresh.
3. Extensions → Extensions → Shipping → Shipping with Qapla’: установите расширение и откройте настройки.
4. На вкладке «Qapla’ account» вставьте ключ канала и нажмите «Save and check the connection».
5. На «Delivery methods» добавьте методы доставки и сохраните.
6. Для Pro: введите ключ или запустите пробный период на вкладке «Licence».