Інтеграція Нової пошти на сайт через API

Покупець обирає місто й відділення прямо в кошику, бачить вартість доставки, а після оформлення замовлення накладна створюється автоматично і статус посилки підтягується на сайт. Розбираємо, як влаштований API Нової пошти, які методи для цього потрібні і де найчастіше виникають проблеми.

Оновлено:

Що дає інтеграція

Без інтеграції менеджер переносить адресу з замовлення в кабінет Нової пошти, створює накладну і вручну надсилає покупцю номер. З інтеграцією це робить сайт:

  • Вибір населеного пункту і відділення чи поштомата з довідника, без помилок у назвах.
  • Розрахунок вартості доставки й орієнтовної дати ще до оплати.
  • Створення експрес-накладної (ЕН) під час оформлення або після підтвердження замовлення.
  • Відстеження статусу посилки і сповіщення покупцю.

Як влаштований 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.

Часті питання

Де взяти ключ API Нової пошти?

У бізнес-кабінеті Нової пошти: «Налаштування» → «Безпека» → «Створити ключ». За даними Нової пошти, це безплатно.

Чи можна автоматично створювати накладні при оформленні замовлення?

Так, через метод створення експрес-накладної. Накладну можна створювати одразу при оформленні або після підтвердження замовлення менеджером — тоді ЕН не з'являються для скасованих замовлень.

Що буде, якщо API Нової пошти тимчасово не відповідає?

Запити ставляться в чергу і повторюються, а збої журналюються і надходять вам у повідомленні.

Пов'язана послуга

Інтеграції та автоматизація

Беремо задачу під ключ: розбираємо ваші процеси, робимо і запускаємо рішення, а потім підтримуємо його.

Вартість
від 15 000 грн

Розкажіть про вашу задачу

Перша консультація безкоштовна. Відповідь протягом 24 годин.

Орієнтовний бюджет (необов'язково)

Не хочете заповнювати форму? Написати в Telegram

Розкажіть про вашу задачу

Перша консультація безкоштовна. Відповідь протягом 24 годин.

Орієнтовний бюджет (необов'язково)

Не хочете заповнювати форму? Написати в Telegram