Укрпошта для інтернет-магазину — це найдешевша доставка по Україні й майже єдиний спосіб дістати покупця в селі, де відділень інших перевізників немає. Ціна цього — довший строк і адресна система, з якою чекаут мусить уміти працювати. Нижче — що саме треба налаштувати, де зазвичай ламається оформлення замовлення і як перевірити, що у вас усе працює.
Чому Укрпошта — це не «ще один перевізник у списку»
З погляду магазину інші перевізники влаштовані просто: є список відділень, покупець обирає своє. Укрпошта влаштована інакше — вона працює від адреси, а не від номера відділення. Одне поштове відділення обслуговує десятки населених пунктів, і покупець зазвичай знає свій індекс або назву села, а не номер відділення.
Практичний наслідок: якщо ви просто виведете в чекаут випадаючий список «оберіть відділення», покупець із села його не знайде. Він побачить райцентр, засумнівається, чи туди йому їхати, — і піде «уточнити». Саме тут зривається більшість замовлень на цьому напрямку, і саме це має вирішити модуль.
Address Classifier: джерело, від якого все залежить
Укрпошта веде офіційний довідник адрес — Address Classifier. Це вивантаження всієї адресної структури країни: області, райони, громади, населені пункти, вулиці, індекси й відділення, що їх обслуговують. Довідник оновлюється: села укрупнюються, індекси змінюються, відділення закриваються.
Звідси два правила, які варто прийняти одразу:
- Не вбивайте адреси руками. Перелік, зібраний одного разу, застаріє протягом кількох місяців, і ви дізнаєтесь про це з відмов на прийманні.
- Не питайте API на кожен символ. Якщо чекаут звертається до перевізника на кожне натискання клавіші, ви прив'язуєте своє оформлення замовлення до чужої доступності.
Офіційна документація й доступ до довідника — на сайті перевізника: ukrposhta.ua.
Головне архітектурне рішення: локальна база проти API наживо
Є два способи під'єднати перевізника, і різниця між ними стає видною рівно тоді, коли щось іде не так.
| Запит до API наживо | Локальна база + синхронізація | |
|---|---|---|
| Швидкість підказки | залежить від мережі | миттєва, з вашої бази |
| Перевізник недоступний | чекаут стає | оформлення проходить |
| Ліміти API | витрачаються на кожен символ | лише на синхронізацію |
| Свіжість даних | завжди поточна | станом на останню синхронізацію |
Модуль Укрпошти побудований за другою схемою: довідник лягає у вашу базу, синхронізація йде за розкладом, а чекаут читає вже локальні дані. Мінус чесно названий — між синхронізаціями дані трохи відстають. Для адресного довідника це прийнятно: села не з'являються щодня.
Та сама модель у Нової Пошти й Meest, тож поведінка чекауту однакова незалежно від того, кого обрав покупець. Усі три — в модулях доставки.
Що налаштувати: покроково
Порядок має значення — кожен наступний крок спирається на попередній.
- 1. Договір і кабінет перевізника. Спершу — договір з Укрпоштою й доступ до кабінету. Без нього немає ключа, а без ключа модуль нічого не синхронізує.
- 2. API-ключ. Отримується в кабінеті. Це той самий API Укрпошти, яким модуль тягне довідник. Ключ зберігається в налаштуваннях магазину, не в коді.
- 3. Перша синхронізація. Довідник вивантажується у вашу базу. Це найдовший крок — далі оновлення інкрементні.
- 4. Розклад. Синхронізація ставиться на крон. Раз на добу — робочий орієнтир для адресного довідника.
- 5. Перевірка чекауту. Оформіть тестове замовлення на село, а не на обласний центр. Якщо адреса знаходиться — модуль працює.
Де це зазвичай ламається
Три помилки, які трапляються найчастіше, і жодна з них не про код.
Ключ поклали в репозиторій. API-ключ — це доступ до вашого кабінету перевізника. Йому місце в налаштуваннях або в.env, які не потрапляють у git. Якщо ключ уже засвітився в комітах — перевипустіть його, а не сподівайтесь, що ніхто не помітив.
Синхронізацію не поставили на крон. Перший імпорт зробили руками, зраділи, що працює, і забули. Через півроку покупці починають скаржитись, що їхнього відділення немає. Формально модуль справний — просто його ніхто не годував.
Тестували на Києві. Обласний центр знайдеться завжди, навіть якщо довідник завантажився наполовину. Тестове замовлення має бути на населений пункт, де ви самі не впевнені, як він пишеться.
Кому Укрпошта дає найбільше
Чесно про те, кому це справді потрібно:
- Якщо ваш покупець за межами міст. Тут в Укрпошти немає конкурента: там, де немає жодного відділення інших перевізників, поштове є майже завжди.
- Якщо ви продаєте недороге. На товарі, де доставка порівнянна з ціною, вибір перевізника вирішує, чи буде замовлення взагалі.
- Якщо ви відправляєте за кордон. Міжнародні відправлення — окремий сценарій, де альтернатив у цій ціновій категорії мало.
І де вона не допоможе: якщо ваш покупець — міський і чекає посилку завтра, Укрпошта не закриє це очікування. Тримайте кілька перевізників і дайте покупцю вибрати — це дешевше, ніж сперечатися з його звичкою.
З чого почати
Найдешевший спосіб перевірити — не читати огляди, а поставити безкоштовну збірку на тестовий домен: модуль Укрпошти вже всередині, як і Нова Пошта з Meest. Прогоніть одне тестове замовлення на село й подивіться, чи знаходиться адреса. Якщо так — питання доставки для вас закрите, і можна повертатися до товарів.