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».