Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Довідники

Знайти одиниці вимірювання

get
/dictionary/measurements

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

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
limitinteger · int32Optional

Максимальна кількість записів на сторінці.

Default: 15Example: 1
pageinteger · int32Optional

Номер сторінки для повернення

Example: 1
Responses
200

Одиниці вимірювання

application/json
current_pageinteger · min: 1Optional

Поточна сторінка.

last_pageinteger · min: 1Optional

Загальна кількість знайдених сторінок.

per_pageinteger · min: 1Optional

Поточний ліміт об’єктів на одній сторінці.

totalintegerOptional

Загальна кількість знайдених об’єктів.

frominteger · nullableOptional
tointeger · nullableOptional
get/dictionary/measurements
GET /v.1.0/dictionary/measurements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 18,
  "per_page": 1,
  "total": 18,
  "from": null,
  "to": null,
  "items": [
    {
      "code": "cm",
      "name": "Centimeter",
      "shortName": "cm",
      "createdAt": "2022-09-29T09:16:04.000000Z",
      "updatedAt": "2023-06-29T12:48:09.000000Z",
      "deletedAt": null
    }
  ]
}

Знайти відділення

get
/divisions

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

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
countryCodes[]array · enumOptional

Щоб отримати список вантажних відділень і поштоматів у певній країні, виберіть потрібний код країни зі списку. Використовуйте код відповідно до стандарту ISO 3166-1 Alpha-2.

Possible values:
limitinteger · int32Optional

Максимальна кількість елементів у відповіді.

Default: 15Example: 1
pageinteger · int32Optional

Номер сторінки для повернення.

Example: 1
settlementIds[]integer[]Optional

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

divisionCategories[]array · enumOptional

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

Possible values:
statuses[]array · enumOptional

Фільтрує відділення за їхнім операційним статусом. Вказує, чи активне відділення, тимчасово закрите або перебуває в підготовці до відкриття.

За замовчуванням повертаються лише відділення зі статусом Working.

Possible values:
prohibitedSendingboolean · enumOptional

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

Possible values:
prohibitedIssuanceboolean · enumOptional

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

Possible values:
latitudenumber · floatOptional

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

longitudenumber · floatOptional

Географічна довгота відділення, що використовується для відображення на мапі та розрахунку відстаней. Приклад значення: 22.9404162762.

Header parameters
Accept-languagestring · enumOptional

Щоб отримати опис відділення певною мовою, передайте необхідний мовний код (стандарт ISO 639-1) у header-параметрі з назвою accept-language. Якщо переклад для вибраної мови відсутній, буде показано англійську мову.

Possible values:
Responses
200

Відділення

application/json
current_pageinteger · min: 1Optional

Поточна сторінка.

last_pageinteger · min: 1Optional

Загальна кількість знайдених сторінок.

per_pageinteger · min: 1Optional

Поточний ліміт об’єктів на одній сторінці.

totalintegerOptional

Загальна кількість знайдених об’єктів.

frominteger · nullableOptional
tointeger · nullableOptional
get/divisions
GET /v.1.0/divisions HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 24942,
  "per_page": 1,
  "total": 24942,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 1,
      "name": "WROCŁAW 1",
      "shortName": "WROCŁAW 1",
      "externalId": "cf909742-1bee-4c97-8d0e-16de519c3220",
      "source": "NPAX",
      "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 dolnośląskie, Wrocław County, Wrocław, Trzebnicka, 50/1A",
      "number": "50/1",
      "status": "Working",
      "customerServiceAvailable": true,
      "divisionCategory": "PostBranch",
      "publicPhones": [],
      "internalPhones": [],
      "responsiblePerson": "Dzhemesiuk Yaroslav",
      "partner": null,
      "ownerDivision": null,
      "latitude": 51.1271131131,
      "longitude": 17.0360840848,
      "distance": null,
      "maxWeightPlaceSender": 200000,
      "maxLengthPlaceSender": 3000,
      "maxWidthPlaceSender": 1700,
      "maxHeightPlaceSender": 1700,
      "maxWeightPlaceRecipient": 200000,
      "maxLengthPlaceRecipient": 3000,
      "maxWidthPlaceRecipient": 1700,
      "maxHeightPlaceRecipient": 1700,
      "prohibitedSending": false,
      "prohibitedIssuance": false,
      "maxCostPlace": 999999,
      "maxDeclaredCostPlace": 999999,
      "workSchedule": [
        {
          "day": "sunday",
          "from": "09:00",
          "to": "18:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "monday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "tuesday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "wednesday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "thursday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "friday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "saturday",
          "from": "09:00",
          "to": "18:00",
          "breakFrom": null,
          "breakTo": null
        }
      ],
      "settings": [],
      "logisticsCode": "Code.1",
      "attributes": {
        "printFormDeliveryRegion": "Balty"
      },
      "createdAt": "2022-09-29T12:40:39.000000Z",
      "updatedAt": "2023-10-16T10:06:35.042931Z",
      "deletedAt": null,
      "fullAddress": {
        "country": "Poland",
        "settlement": "Wrocław",
        "street": "Trzebnicka",
        "building": "50/1A",
        "note": "",
        "zipcode": "50-231"
      }
    }
  ]
}

Отримати офлайн-довідник відділень

get
/dictionary/divisions

Цей API метод повертає маніфест із посиланнями на файли офлайн-довідника, які містять дані про власні та партнерські вантажні відділення (divisions) і поштомати.

Відповідь містить URL-адреси актуальних локалізованих файлів довідника, підготовлених для використання в офлайн-режимі. Файл зазвичай містить такі дані, як назва відділення, номер, адреса, ідентифікатор, інформація про країну та місто, тип відділення, графік роботи, обідні перерви (для європейських відділень, де це застосовується) та інші релевантні атрибути. Ці дані можуть бути використані для створення транспортного документа (відправлення).

Файли довідника містять дані про всі відділення та поширюються у вигляді локалізованих стиснених JSON-архівіву форматі .json.gz.

🔹Довідник оновлюється один раз на добу та призначений для використання в офлайн-режимі й періодичної синхронізації. Для отримання актуальної версії довідника необхідно використовувати URL, отриманий у поточній відповіді API. Не рекомендується використовувати URL, отримані з попередніх відповідей.

Query parameters
measurementUnitsstring · enumOptional

Повертає метричну систему у кілограмах (kg) та сантиметрах (cm), або грамах (g) та міліметрах (mm).

За замовчуванням повертається kg_cm. Якщо передати інше значення, буде повернуто помилку валідації 422.

Default: kg_cmPossible values:
Header parameters
Accept-languagestring · enumOptional

Щоб отримати вміст довідника певною мовою, передайте код потрібної мови (ISO 639-1) у заголовку Accept-Language.

Якщо переклад для вибраної мови відсутній, буде використано англійську мову. За замовчуванням використовується en.

Default: enPossible values:
Responses
200

Маніфест офлайн-довідника відділень

application/json
get/dictionary/divisions
GET /v.1.0/dictionary/divisions HTTP/1.1
Host: api-stage.novapost.com/
Accept: */*

{
  "base_version": {
    "unix_time": 1786294841,
    "url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/base.json.gz"
  },
  "deltas": [
    {
      "unix_time_from": 1786035632,
      "unix_time_till": 1786122036,
      "url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786122036.json.gz"
    },
    {
      "unix_time_from": 1786122036,
      "unix_time_till": 1786208439,
      "url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786208439.json.gz"
    },
    {
      "unix_time_from": 1786208439,
      "unix_time_till": 1786294841,
      "url": "https://api-cdn.novapost.com/dictionary/divisions/api/en/delta_1786294841.json.gz"
    }
  ]
}

Знайти валюти

get
/dictionary/currencies

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

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
limitinteger · int32Optional

Максимальна кількість елементів на сторінці.

Default: 15Example: 1
pageinteger · int32Optional

Номер сторінки для повернення.

Example: 1
codes[]string · int32Optional

Коди валют.

Example: UAH
Responses
200

Валюти

application/json
current_pageinteger · min: 1Optional

Поточна сторінка.

last_pageinteger · min: 1Optional

Загальна кількість знайдених сторінок.

per_pageinteger · min: 1Optional

Поточний ліміт об’єктів на одній сторінці.

totalintegerOptional

Загальна кількість знайдених об’єктів.

frominteger · nullableOptional
tointeger · nullableOptional
get/dictionary/currencies
GET /v.1.0/dictionary/currencies HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 1,
  "total": 1,
  "from": null,
  "to": null,
  "items": [
    {
      "code": "USD",
      "numCode": "840",
      "name": "US Dollar",
      "shortName": "US Dollar",
      "symbol": "$",
      "createdAt": "2022-09-27T11:55:52.000000Z",
      "updatedAt": "2022-09-27T11:55:52.000000Z",
      "deletedAt": null
    }
  ]
}

Знайти товарні класифікатори (УКТ ЗЕД)

get
/dictionary/classifier

Цей API метод дозволяє отримати список товарних класифікаторів (УКТ ЗЕД). Товарні класифікатори — це попередньо визначені категорії або класифікації, що використовуються для віднесення різних типів вантажів до відповідних груп. Використовуючи цей метод, можна отримати перелік класифікаторів, які підтримуються системою. Відповідь містить деталі щодо кожного класифікатора, зокрема ідентифікатор, назву, опис, категорію, приклади та іншу релевантну інформацію. Ці дані можуть бути використані для створення транспортного документа (відправлення).

Як це працює:

  • Метод повертає класифікатори для країни отримувача, зазначеної в параметрі country-code.

  • Формат кодів УКТ ЗЕД залежить від вибраної країни, наприклад:

    • Для країн призначення Канада (CA) та Молдова (MD) коди УКТ ЗЕД проходять сувору перевірку й мають містити рівно 10 цифр.

    • Будь-які нечислові символи в HsCode будуть автоматично видалені перед валідацією.

  • Параметр keyword дозволяє шукати конкретний товарний класифікатор.

  • Якщо fuzzy=true, пошук включатиме схожі результати на основі нечіткого збігу.

Обмеження:

  • Деякі країни можуть не підтримувати отримання УКТ ЗЕД через API.

  • Результати залежать від актуальності оновлення бази класифікаторів.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
country-codestringOptional

Код країни за стандартом ISO 3166-1 Alpha-2, для якої потрібен класифікатор УКТ ЗЕД. Цей параметр стосується країни отримувача, а не відправника. Формат кодів УКТ ЗЕД відрізняється залежно від країни, наприклад: - UA – повертає 8-значні коди. - CA або MD – повертає 10-значні коди.
Приклад: якщо потрібні коди УКТ ЗЕД для Канади, використовуйте country-code=CA.

Example: CA
fuzzyboolean · enumOptional

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

Example: truePossible values:
keywordstringOptional

Ключове слово для пошуку класифікатора.

Example: book
localestringOptional

Мовний код відповідно до стандарту ISO 639-1.

Example: uk
sizeinteger · int32Optional

Кількість відповідних класифікаторів для повернення.

Example: 15
Responses
200

Список товарних класифікаторів (УКТ ЗЕД)

application/json
statusbooleanOptional
sourcestringOptional
errorstringOptional
get/dictionary/classifier
GET /v.1.0/dictionary/classifier HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "status": true,
  "source": "tda",
  "error": "",
  "items": [
    {
      "id": "b1f6e933-a5fd-3c76-8663-49ad7b454bdd",
      "hsCode": "85171400",
      "category": {
        "en": "Electronics",
        "currentLocal": "Електроніка"
      },
      "subCategory": {
        "en": "Laptops, Computers And Peripherals",
        "currentLocal": "Ноутбуки, комп'ютери та периферійні пристрої"
      },
      "keywords": {
        "en": "Avonic Video Conference Camera, System for video conferences, IP conference phone, Logitech ConferenceCam, Prestigio Solutions, UHD video conference camera, USB speakerphone, Device for conference communication, Wireless speakerphone, Video conference camera, VKZ camera, Video conference kit, Conference Lenovo hub, Speakerphone, Speaker system, Audio conference system, Conference phone, Video conference system, Notification system, System console",
        "currentLocal": "Avonic Video Conference Camera, Cистема для відеоконференцій, IP конференц телефон, Logitech ConferenceCam, Prestigio Solutions, UHD відео конференц камера, USB спікерфон, Апарат для конференц зв'язку, Бездротовий спікерфон, Камера відеоконференції, Камера ВКЗ, Комплект для відеоконференцзв'язку, Конференц хаб Lenovo, Спікерфон, Акустична система, Аудіо конференц система, Конференц-телефон, Система відеоконференції, Система оповіщення, Системна консоль"
      },
      "product": {
        "en": "Conference equipment",
        "currentLocal": "Конференц-обладнання"
      },
      "description": {
        "en": "Electrical machinery and equipment and parts thereof; sound recorders and reproducers, television image and sound recorders and reproducers, and parts and accessories of such articles | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, including apparatus for communication in a wired or wireless network (such as a local or wide area network), other than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528; parts thereof: | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks : | Other telephones for cellular networks or for other wireless networks | Other",
        "currentLocal": "Електричні машини та обладнання та їх частини; апарати для запису та відтворення звуку, апарати для запису та відтворення телевізійного зображення та звуку, а також частини та приладдя до таких виробів | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж; інша апаратура для передачі або прийому голосу, зображень або інших даних, включаючи апаратуру для зв'язку в дротовій або бездротовій мережі (такій як локальна або глобальна мережа), крім апаратури для передачі або прийому товарних позицій 8443, 8525, 8527 або 8528; їх частини: | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж: | Інші телефони для стільникових мереж або для інших бездротових мереж | Інший"
      },
      "exportFromUA": true,
      "importToUA": true
    }
  ]
}

Знайти налаштування митних зборів

get
/dictionary/customs-fees/{code}

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

Якщо значення customsFeesActive дорівнює false, відправник не може виступати платником митних зборів для вибраної країни.

Поля minDeclaredCost та maxDeclaredCost визначають діапазон оціночної вартості посилки (у валюті країни одержувача), в межах якого доступна опція сплати митних зборів відправником.

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

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

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
codestringRequired

Альфа-код країни призначення відповідно до стандарту ISO 3166-1 Alpha-2.

Example: PL
Responses
200

Успішна відповідь із налаштуваннями митних зборів

application/json
customsFeesActivebooleanOptional

Ознака можливості сплати митних зборів відправником.

Можливі значення:

  • true — оплата можлива
  • false — оплата неможлива
Example: true
minDeclaredCostnumberOptional

Мінімальна оціночна вартість посилки у валюті країни одержувача.

Example: 10
maxDeclaredCostnumberOptional

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

Example: 500
get/dictionary/customs-fees/{code}
GET /v.1.0/dictionary/customs-fees/{code} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "customsFeesActive": true,
  "maxDeclaredCost": 500,
  "minDeclaredCost": 10
}

Довідник населених пунктів із забороною видачі

get
/dictionary/settlements/prohibited-issuance

Цей API метод повертає маніфест із посиланнями на офлайн-файли довідника, що містять перелік населених пунктів України, у яких заборонена видача (отримання) відправлень. Довідник охоплює всі типи населених пунктів і призначений для валідації адрес, перевірки доступності доставки та логістичних обмежень.

Відповідь містить URL-адреси актуальних локалізованих файлів довідника, підготовлених для офлайн-використання. Кожен файл містить дані про населений пункт, зокрема адміністративну ієрархію, координати, поштові індекси, альтернативні назви та ознаки заборони.

Файли довідника поширюються у вигляді локалізованих стиснутих JSON-архівів.

🔹Ключові можливості:

  • Повертає JSON-маніфест із URL-адресами файлів довідника.

  • Файли надаються у форматі .json.gz.

  • Підтримується локалізація (locale="uk", locale="en").

  • Містить лише населені пункти з prohibitedIssuance = true.

  • Призначено для офлайн-використання та періодичної синхронізації.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Responses
200

Маніфест довідника населених пунктів із забороною видачі

application/json
unix_timeintegerRequired

Unix timestamp, що вказує час генерації довідника.

Example: 1766120417
urlsstring · uri[]Required

Список URL-адрес локалізованих офлайн-файлів довідника.

Example: https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/en/settlements.json.gz
get/dictionary/settlements/prohibited-issuance
GET /v.1.0/dictionary/settlements/prohibited-issuance HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "unix_time": 1766120417,
  "urls": [
    "https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/en/settlements.json.gz",
    "https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/uk/settlements.json.gz"
  ]
}

Офлайн-довідник населених пунктів

get
/dictionary/settlements/versions

Цей API-метод повертає маніфест із посиланнями на файли офлайн-довідників, що містять дані про населені пункти. Довідники формуються на основі набору даних населених пунктів і надаються окремо для кожної країни.

Відповідь містить URL-адреси актуальних локалізованих файлів довідника, підготовлених для використання в офлайн-режимі. Кожен файл містить дані про населені пункти, такі як адміністративна ієрархія, координати, поштові індекси, альтернативні назви та інші релевантні атрибути.

Кожен запит повертає файли довідника для конкретної країни.

Файли довідника поширюються у вигляді локалізованих стиснених JSON-архівів.

🔹Основні можливості:

  • Повертає JSON-маніфест із URL-адресами файлів довідника.

  • Файли надаються у форматі .json.gz.

  • Підтримується локалізація через заголовок Accept-language (за замовчуванням: en).

  • Окремі файли для кожної країни (UA, MD).

  • Побудовано на основі даних довідника населених пунктів.

  • Оновлюється один раз на добу.

  • Призначено для використання в офлайн-режимі та періодичної синхронізації.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
countryCodestring · enumRequired

Код країни, для якої необхідно повернути довідник населених пунктів (ISO 3166-1 Alpha-2).

Example: UAPossible values:
Header parameters
Accept-languagestring · enumOptional

Щоб отримати вміст довідника певною мовою, передайте код потрібної мови (стандарт ISO 639-1) у заголовку з назвою accept-language. Якщо переклад для вибраної мови відсутній, буде відображено англійську мову.

Possible values:
Responses
200

Маніфест офлайн-довідника населених пунктів

application/json
unix_timeintegerRequired

Unix-часова мітка, що вказує час генерації довідника.

Example: 1776225628
urlsstring · uri[]Required

Список публічних URL-адрес локалізованих файлів офлайн-довідника.

Example: https://api-cdn.novapost.com/dictionary/settlements/api/UA/uk/base.json.gz
get/dictionary/settlements/versions
GET /v.1.0/dictionary/settlements/versions?countryCode=UA HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "unix_time": 1776225628,
  "base_version": {
    "unix_time": 1776225628
  },
  "urls": [
    "https://api-cdn.novapost.com/dictionary/settlements/api/UA/uk/base.json.gz"
  ]
}

Знайти населені пункти

get
/settlements

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

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
countryCodes[]array · enumOptional

Для отримання списку населених пунктів у певній країні виберіть необхідний код країни зі списку. Використовуйте код відповідно до стандарту ISO 3166-1 Alpha-2.

Possible values:
limitinteger · int32Optional

Максимальна кількість елементів для повернення.

Default: 15Example: 1
pageinteger · int32Optional

Номер сторінки для повернення.

Example: 1
textSearchstringOptional

Пошук за будь-яким текстом.

Responses
200

населені пункти

application/json
current_pageinteger · min: 1Required

Поточна сторінка.

last_pageinteger · min: 1Required

Загальна кількість знайдених сторінок.

per_pageinteger · min: 1Required

Поточний ліміт об'єктів на одній сторінці.

totalintegerRequired

Загальна кількість знайдених об'єктів.

frominteger · nullableOptional
tointeger · nullableOptional
get/settlements
GET /v.1.0/settlements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 80,
  "per_page": 15,
  "total": 1186,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 118064,
      "name": "місто Київ",
      "country": {
        "code": "UA",
        "name": "Україна"
      },
      "region": {
        "id": 406,
        "name": "Київська область",
        "parent": null
      },
      "latitude": 50.450418,
      "longitude": 30.523541,
      "postCode1": "01001",
      "postCode2": "04215",
      "alternativeNames": [
        "kyiv",
        "місто київ",
        "misto kiyiv",
        "город киев",
        "gorod kiev",
        "city kyiv"
      ],
      "externalId": "e718a680-4b33-11e4-ab6d-005056801329",
      "boost": 504,
      "prohibitedIssuance": false,
      "prohibitedSending": false,
      "createdAt": "2022-10-01T15:50:20.000000Z",
      "updatedAt": "2026-04-03T07:17:49.715827Z",
      "deletedAt": null
    }
  ]
}

Знайти вулиці

get
/streets

Цей API-метод дозволяє отримати список вулиць, доступних у різних населених пунктах. Передаючи код країни як параметр або settlementId як параметр, ви можете отримати повний список вулиць та пов’язану з ними інформацію. Метод також підтримує пошук за назвою вулиці. Відповідь зазвичай містить інформацію, таку як назва вулиці, назва населеного пункту, ідентифікатор та інші релевантні атрибути. Ці дані можуть бути корисними для створення транспортного документа (відправлення).

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
countryCodes[]string[]Optional

Список кодів країн (ISO 3166-1 Alpha-2) для фільтрації вулиць.

namestringOptional

Фільтр за назвою вулиці.

limitinteger · int32 · min: 1 · max: 100Optional

Максимальна кількість елементів для повернення.

Default: 15Example: 15
pageinteger · min: 1Optional

Номер сторінки для повернення.

Example: 1
Responses
200

вулиці

application/json
current_pageinteger · min: 1Required

Поточна сторінка.

last_pageinteger · min: 1Required

Загальна кількість знайдених сторінок.

per_pageinteger · min: 1Required

Поточний ліміт об’єктів на одній сторінці.

totalintegerRequired

Загальна кількість знайдених об’єктів.

frominteger · nullableOptional
tointeger · nullableOptional
get/streets
GET /v.1.0/streets HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 50,
  "total": 16,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 4582148,
      "name": "вул. Хрещатик",
      "settlement": {
        "id": 118064,
        "name": "місто Київ"
      },
      "countryCode": "UA",
      "latitude": 0,
      "longitude": 0,
      "alternativeNames": [
        "вул. хрещатик",
        "vul. khreshchatik",
        "крещатик",
        "kreshchatik",
        "khreshchatyk"
      ],
      "externalId": "ad090b1f-6845-11e6-8304-00505688561d",
      "createdAt": "2024-02-03T11:40:00.000000Z",
      "updatedAt": "2025-04-04T00:47:48.223218Z",
      "deletedAt": null
    }
  ]
}
ПопередняАвторизація
НаступнаСервіси

Останнє оновлення