Укр
Довідник відділень
integration

Довідник відділень – важливий елемент інтеграції з API NovaPost. Він надає актуальну інформацію про всі відділення та поштомати NovaPost та партнерів у країнах присутності, включаючи адреси, графіки роботи, координати та інші параметри.

Метод довідника відділень API NovaPost дозволяє гнучко працювати з актуальною інформацією про відділення в режимі реального часу або завантажувати повний довідник для подальшого використання. Вибір підходу залежить від ваших потреб у обсязі даних та частоті їх оновлення.

Отримання даних про відділення в онлайн-режимі

Для отримання інформації про відділення в реальному часі можна скористатися запитом до API.

Приклад запиту:

GET https://api.novapost.com/v.1.0/divisions?countryCodes[]=PL&limit=100&name=*WROCŁAW*

Можливі додаткові фільтри:

  • 1
    divisionCategories[]: Категорії відділень. Можливі значення: PostBranch, CargoBranch, Postomat, PUDO.
  • 2
    countryCodes[]: Код країни в форматі двох літер (наприклад, PL, UA, HU).
  • 3
    name: Назва міста мовою країни, де це місто знаходиться.

    Параметр підтримує тільки повне співпадіння назви міста. Наприклад: name=WROCŁAW. Для часткового пошуку використовуйте символи підстановки (*). Наприклад: name=*WROCŁAW*. У разі відсутності співпадінь повертається порожня відповідь.

  • Приклад відповіді:

    {
        "id": 1,
        "name": "WROCŁAW 1",
        "shortName": "WROCŁAW 1",
        "number": "50/1",
        "countryCode": "PL",
        "settlement": {
            "id": 26061,
            "name": "Wroclaw",
            "region": {
                "id": 344,
                "name": "Wrocław County",
                "parent": {
                    "id": 2,
                    "name": "Lower Silesian voivodeship"
                }
            }
        },
        "address": "50-231, Polska, Województwo dolноśląське, Wrocław County, Wrocław, Trzebnickа, 50/1A",
        "status": "Working",
        "divisionCategory": "PostBranch",
        "latitude": 51.1271131131,
        "longitude": 17.0360840848,
        "workSchedule": [
            {
                "day": "monday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "tuesday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "wednesday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "thursday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "friday",
                "from": "08:00",
                "to": "20:00"
            },
            {
                "day": "saturday",
                "from": "09:00",
                "to": "18:00"
            },
            {
                "day": "sunday",
                "from": "09:00",
                "to": "18:00"
            }
        ]
    }

Завантаження всього довідника відділень

Якщо вам потрібна повна інформація про всі відділення, а не тільки частина даних, рекомендується завантажити довідник відділень архівом.

Приклад запиту:

GET https://api.novapost.com/divisions/versions

Цей запит можна виконувати без токена авторизації. За потреби, можна змінити мову відповіді довідника передавши параметр мови в заголовку запиту, наприклад Accept-Language:uk.

  • Приклад відповіді:

    {
        "base_version": {
            "unix_time": 1710198943,
            "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/base.json.gz"
        },
        "deltas": [
            {
                "unix_time_from": 1709928943,
                "unix_time_till": 1709961345,
                "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/delta_1709961345.json.gz"
            },
            {
                "unix_time_from": 1709961345,
                "unix_time_till": 1710015350,
                "url": "https://api-cdn.novapost.pl/dictionary/divisions/mobile/full/en/delta_1710015350.json.gz"
            }
        ]
    }

  • 1
    base_version: Посилання на повний довідник відділень на момент останнього оновлення.
  • 2
    deltas: Посилання на файли, які містять оновлення до довідника відділень, що були зафіксовані після створення базової версії.

Використання архіву та дельт

Завантаження архіву базової версії довідника надає повний список відділень. Надалі можна оновлювати лише зміни, використовуючи файли дельт, що значно зменшує об'єм даних для обробки.