Віджет вибору відділення

Додайте віджет вибору відділення або поштомата на будь-яку вебсторінку за лічені хвилини — з Google Maps, фільтрами та підтримкою TypeScript.

Відкрити PlaygroundШвидкий СтартДовідник APIChangelog

Два варіанти відображення

Режим карти (Google Maps) або режим віджета (список із пошуком і фільтрами). Обидва варіанти підтримують однакові параметри та події.

Лінива ініціалізація iframe

<iframe> створюється лише під час першого виклику show() — до цього моменту він не створюється.

Без потреби в API-ключі

Усі запити до Nova Post API виконуються через проксі-сервер.

Швидкий старт — UMD через <script>

Працює на будь-якій HTML-сторінці без потреби в етапі збірки.

<!-- 1. Container — must have an explicit height -->
<div id="nova-post-widget" style="width:100%;height:600px"></div>

<!-- 2. Load the SDK -->
<script src="https://integration-widget.novapost.com/sdk.min.js"></script>

<script>
  const widget = new NovaPostWidget.NovaPostWidget({
    container: '#nova-post-widget',
    locale:    'en',
    variant:   'widget',   // 'map' | 'widget'
    viewMode:  'container', // 'container' | 'popup'
    country:   'UA',
    city:      'Київ',
    shipmentRole: 'recipient', // 'recipient' | 'sender'
    theme: 'light', // 'light' | 'dark'

    onReady: () => console.log('Widget ready'),

    onSelect: (division) => {
      console.log(division.name, division.displayAddress)
      widget.hide()
    },
    
    onClear: () => {
      console.log('Selection cleared')
    },

    onError: (err) => console.error(err.message),
  })

  widget.show()
</script>

Конфігурація — WidgetConfig

ПАРАМЕТР	ТИП	ОБОВ.	ЗА ЗАМОВЧ.	ОПИС
container	string | HTMLElement	Yes	—	CSS-селектор або DOM-елемент для вбудовування віджета
locale	'uk' | 'en' | 'de' | 'cs'	—	'en'	Мова інтерфейсу
variant	'map' | 'widget'	—	'map'	Режим відображення: map — карта widget — пошук, список відділень і карта
viewMode	'container' | 'popup'	—	'container'	Вбудоване відображення або спливаюче вікно
shipmentRole	'recipient' | 'sender'	—	'recipient'	Визначає, чи використовується віджет для вибору відділення відправника або отримувача
country	string | null	—	—	Код країни за стандартом ISO, наприклад 'UA'
city	string | null	—	—	Назва міста для попереднього вибору
theme	'light' | 'dark'	—	'light'	Тема інтерфейсу користувача
senderCountry	string | null	—	—	ISO-код країни відправника, наприклад 'UA'; відкриває можливість вибору партнерських пунктів PUDO (UPS) для підтримуваних країн [PL, UA]
divisionId	number | null	—	—	Попередній вибір конкретного відділення
divisionCategories	DivisionType[]	—	—	Фільтр за типом відділення; якщо параметр не вказано, відображаються всі типи
autoShow	boolean	—	false	Автоматично викликає show() після ініціалізації; працює лише при 'viewMode' = 'container'
mobileBreakpointPx	number	—	768	Нижче цієї ширини області перегляду спливаюче вікно відкривається в повноекранному режимі
onSelect	(division: DivisionItem) => void	—	—	Викликається, коли користувач підтверджує вибір відділення
onClear	() => void	—	—	Викликається після очищення вибраного відділення
onReady	() => void	—	—	Викликається після завантаження iframe та його готовності до роботи
onError	(error: Error) => void	—	—	Викликається у разі виникнення помилки виконання всередині iframe
onClose	(reason?) => void	—	—	Викликається після закриття спливаючого вікна

API-методи

widget.show() Відображає віджет. Під час першого виклику створюється iframe (лінива ініціалізація).

У режимі container встановлює для iframe значення display: block. У режимі popup відкриває спливаюче вікно. Під час кожного виклику (в обох режимах), після готовності віджета, карта автоматично центрується на раніше вибраному відділенні.

widget.hide() Приховує віджет без видалення iframe.

У режимі container встановлює значення display: none. У режимі popup — закриває спливаюче вікно. Прямий виклик hide() не викликає onClose; цей callback викликається лише тоді, коли закриття ініціює сам віджет (натискання клавіші Escape, клік по фону спливаючого вікна або після вибору відділення), після чого hide() викликається внутрішньо.

widget.updateParams(params) Оновлює параметри без повторного створення iframe.

Оновлює параметри city, country, senderCountry, divisionId, divisionCategories, theme та locale. Якщо метод викликати до події onReady, зміни буде поставлено в чергу та автоматично застосовано після готовності віджета.

widget.destroy() Видаляє iframe, елементи спливаючого вікна та всі обробники подій.

Викликайте метод під час зміни маршруту в SPA або під час демонтування компонента (Vue onUnmounted, React useEffect cleanup).

Варіанти та Режими Відображення

ВАРІАНТ	РЕЖИМ ВІДОБРАЖЕНЯ	РЕЗУЛЬТАТ
map	container	Google Maps, вбудована безпосередньо на сторінку
map	popup	Кнопка відкриття → після натискання відкривається спливаюче вікно з Google Maps
widget	container	Пошук відділень зі списком і картою, вбудованими безпосередньо на сторінку
widget	popup	Кнопка відкриття → після натискання відкривається спливаюче вікно з пошуком відділень, списком і картою

onSelect callback — поля DivisionItem

Повний об'єкт, який передається до обробника після підтвердження користувачем вибору відділення:

• onSelect отримує об'єкт відділення.
• onClear очищає стан застосунку.

let selectedDivision = null

onSelect: (division) => {
  selectedDivision = division
  division.id               // number  — unique ID
  division.name             // string  — full name
  division.shortName        // string  — short name
  division.displayAddress   // string  — formatted address
  division.divisionCategory // 'PostBranch' | 'CargoBranch' | 'Postomat' | 'PUDO'
  division.source           // 'NPAX' | 'NPUA' | 'InPost' | 'UPS' | ...
  division.latitude         // number | null
  division.longitude        // number | null
  division.maxWeightPlaceRecipient  // number (kg)
  division.maxLengthPlaceRecipient  // number (cm)
  division.addressParts?.region
  division.addressParts?.city
  division.addressParts?.street
  division.addressParts?.postCode
},

onClear: () => {
  selectedDivision = null // also clear the corresponding host form fields
}