Гайд

API Нової Пошти: як підключити доставку до сайту

Цей гайд для розробників і власників магазинів, які хочуть, щоб місто, відділення і накладна з'являлися на сайті автоматично. Ми пройшли цей шлях на реальному магазині Area 636 і зібрали тут те, що знадобиться, включно з місцями, де найчастіше спотикаються.

Якщо не хочете розбиратися самі — ми підключимо це за вас.

Як отримати API-ключ

  1. Увійдіть в особистий кабінет Нової Пошти як бізнес-клієнт (потрібен договір або ФОП-кабінет).
  2. Відкрийте Налаштування → Безпека.
  3. Створіть API-ключ і збережіть його.

Ключ дає доступ до ваших відправлень, тому зберігайте його тільки на сервері, в змінних оточення. Ніколи не вставляйте ключ у JavaScript, який виконується в браузері: його побачить будь-хто через інструменти розробника.

Як влаштовані запити

У всіх методів одна адреса і один формат. Ви надсилаєте POST з JSON, де вказуєте модель, метод і параметри:

const NP_URL = 'https://api.novaposhta.ua/v2.0/json/';

async function np(modelName, calledMethod, methodProperties = {}) {
  const res = await fetch(NP_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apiKey: process.env.NP_API_KEY,
      modelName,
      calledMethod,
      methodProperties,
    }),
  });
  const json = await res.json();
  if (!json.success) {
    throw new Error(json.errors?.join('; ') || 'Nova Poshta API error');
  }
  return json.data;
}

Важливий нюанс: API відповідає з HTTP-статусом 200 навіть тоді, коли запит не вдався. Тому перевіряйте поле success у відповіді, а не лише статус HTTP. Інакше помилки мовчки проходитимуть далі, і ви дізнаєтеся про них від покупця.

Пошук міста

const cities = await np('Address', 'searchSettlements', {
  CityName: 'Біла Церква',
  Limit: '10',
  Page: '1',
});

Використовуйте цей метод для поля з підказками: покупець вводить перші літери, сайт показує варіанти.

Список відділень

const warehouses = await np('Address', 'getWarehouses', {
  CityRef: cityRef, // Ref міста з попереднього кроку
  Limit: '50',
  Page: '1',
});

Відділень по країні десятки тисяч. Не завантажуйте їх щоразу при відкритті кошика: кешуйте список на своєму сервері й оновлюйте за розкладом (наприклад, раз на добу). Це і швидше для покупця, і не впирається в обмеження API.

Створення накладної

Накладна (експрес-накладна, ТТН) створюється методом save моделі InternetDocument. Для неї потрібні Ref відправника, його контактної особи й адреси — їх один раз отримують через моделі Counterparty і ContactPerson і зберігають у налаштуваннях магазину.

const [ttn] = await np('InternetDocument', 'save', {
  PayerType: 'Recipient',
  PaymentMethod: 'Cash',
  CargoType: 'Parcel',
  Weight: '1',
  ServiceType: 'WarehouseWarehouse',
  SeatsAmount: '1',
  Description: 'Настільна гра',
  Cost: '1500',
  CitySender: SENDER_CITY_REF,
  Sender: SENDER_REF,
  SenderAddress: SENDER_WAREHOUSE_REF,
  ContactSender: SENDER_CONTACT_REF,
  SendersPhone: SENDER_PHONE,
  CityRecipient: order.cityRef,
  RecipientAddress: order.warehouseRef,
  // + дані отримувача
});

// ttn.IntDocNumber — номер ТТН, який надсилаємо покупцю

Відстеження посилки

const statuses = await np('TrackingDocument', 'getStatusDocuments', {
  Documents: [{ DocumentNumber: ttn.IntDocNumber, Phone: order.phone }],
});

Передавайте номер телефону отримувача чи відправника: без нього відповідь міститиме менше даних. Статуси ми оновлюємо фоновим завданням за розкладом і змінюємо статус замовлення в магазині автоматично.

Часті помилки

Ключ у браузері. Найпоширеніша і найнебезпечніша: ключ видно в коді сторінки. Усі запити — тільки через ваш сервер.

Перевірка тільки HTTP-статусу. Див. вище: помилки приходять з кодом 200.

Завантаження всіх відділень у кошику. Кешуйте.

Ref замість назв. API працює з ідентифікаторами (Ref), а не з назвами міст. Зберігайте в замовленні саме Ref міста і відділення, інакше накладна не створиться через розбіжність у написанні.

Тестування на реальних відправленнях. Створюйте тестові накладні й видаляйте їх методом delete моделі InternetDocument, поки вони не передані в доставку.

Підключимо за вас

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

Написати нам

Або напишіть у Telegram.