Що дає інтеграція
Без інтеграції менеджер переносить адресу з замовлення в кабінет Нової пошти, створює накладну і вручну надсилає покупцю номер. З інтеграцією це робить сайт:
- Вибір населеного пункту і відділення чи поштомата з довідника, без помилок у назвах.
- Розрахунок вартості доставки й орієнтовної дати ще до оплати.
- Створення експрес-накладної (ЕН) під час оформлення або після підтвердження замовлення.
- Відстеження статусу посилки і сповіщення покупцю.
Як влаштований API Нової пошти
API має одну адресу для JSON-запитів — https://api.novaposhta.ua/v2.0/json/ (є й варіант для XML). Кожен запит — це JSON з чотирма полями: apiKey (ваш ключ), modelName (група методів), calledMethod (метод) і methodProperties (параметри). Відповідь містить ознаку success, дані і окремі масиви помилок та попереджень.
Ключ API створюється в бізнес-кабінеті: «Налаштування» → «Безпека» → «Створити ключ». За даними Нової пошти, це безплатно. Ключ прив'язаний до вашого облікового запису відправника, тож зберігати його треба на сервері, а не в коді сторінки.
Методи, які знадобляться
Для типового інтернет-магазину вистачає кількох методів:
| Задача | Модель і метод | Що врахувати |
|---|---|---|
| Пошук населеного пункту | AddressGeneral · searchSettlements | Повертає ідентифікатори (Ref) населеного пункту, які далі використовуються в інших методах. |
| Список відділень | AddressGeneral · getWarehouses | Відділень багато — довідник варто зберігати у себе й регулярно оновлювати, а не запитувати щоразу. |
| Вартість доставки | InternetDocument · getDocumentPrice | Потрібні міста відправника й отримувача, тип доставки, вага, оголошена вартість. |
| Орієнтовна дата доставки | InternetDocument · getDocumentDeliveryDate | Залежить від типу доставки і міст; показуйте її як орієнтовну. |
| Створення накладної | InternetDocument · save | Працює лише з ключем API; потрібні дані відправника, отримувача, вантажу і способу оплати. |
| Статус посилки | TrackingDocument · getStatusDocuments | Повну інформацію API показує лише разом з номером телефону з накладної. |
Готовий модуль чи власна інтеграція
Нова пошта пропонує API і програмні модулі для інтеграції сайтів і облікових систем. Для поширених CMS існують і сторонні модулі. Вибір залежить від того, наскільки ваш процес відрізняється від типового.
| Готовий модуль | Власна інтеграція | |
|---|---|---|
| Коли підходить | Стандартна CMS, типовий процес: одне місце відправки, оплата при отриманні або онлайн | Власний сайт, кілька складів, нестандартні правила, зв'язок з CRM чи обліком |
| Гнучкість | У межах налаштувань модуля | Будь-які правила: хто, коли і з якими даними створює накладну |
| Підтримка | Залежить від автора модуля і оновлень CMS | Код ваш; зміни в API Нової пошти треба відстежувати |
| Обробка збоїв | Як передбачив автор модуля | Черги, повтори і сповіщення під ваш процес |
Типові проблеми
Що варто передбачити заздалегідь:
- Збереження назв замість ідентифікаторів. Назви міст і відділень змінюються, а замовлення має посилатися на Ref, який повернув API.
- Застарілий довідник відділень. Відділення відкриваються, закриваються і змінюють номери — довідник треба оновлювати за розкладом.
- Ігнорування попереджень. API може виправити параметри запиту самостійно (наприклад, змінити тип вантажу) і повідомити про це в попередженнях. Їх варто журналювати, інакше вартість чи тип відправлення можуть відрізнятися від очікуваних.
- Недоступність API в момент оформлення. Замовлення не повинно губитися: запит на створення накладної ставиться в чергу і повторюється, а про збій надходить сповіщення.
- Помилки в даних отримувача. Телефон і ПІБ варто перевіряти на формат ще у формі замовлення, а не після відмови API.
- Ключ у відкритому коді. Запити до API мають іти з вашого сервера; ключ не повинен потрапляти в браузер.
Що підготувати перед зверненням
Для оцінки й запуску знадобиться:
- Обліковий запис відправника в бізнес-кабінеті Нової пошти і ключ API.
- Звідки відправляєте: одна адреса чи кілька складів.
- Які типи доставки потрібні: відділення, поштомат, адресна доставка.
- Як оплачується доставка і чи є післяплата або контроль оплати.
- Коли має створюватися накладна: одразу після оформлення чи після підтвердження менеджером.
- На чому працює сайт і чи потрібна передача даних у CRM або облік.
Скільки коштує інтеграція
Одна інтеграція — від 15 000 грн. Вартість залежить від кількості сценаріїв (наприклад, лише розрахунок вартості, чи ще й створення накладних, трекінг і повернення) і стану коду, до якого підключаємось. Якщо сайт не на Laravel, інтеграцію можна зробити окремим сервісом, який працює з сайтом через API.