ЛадДля агентів ↗
Довідник/Адреси

Адреси: територія, будинок і доставка

Одна адреса може мати кілька зовнішніх ID. Кожне джерело описує її для своєї задачі.

П’ять частин адресних даних

  1. Територія. Країна, область, район, громада та населений пункт. Для української ієрархії вже є КАТОТТГ.
  2. Вулиця й будинок. Офіційні адресні записи, перейменування та рішення. Досліджуємо ЄДРА і джерела громад; відкритий повний API ще не підтверджено.
  3. Поштовий індекс. Відповідність адреси поштовому обслуговуванню. Є класифікатор Укрпошти; доступ із токеном не тестували.
  4. Місце доставки. Населений пункт у перевізника, відділення, поштомат чи кур’єрська адреса. Це окремі відповідності до Нової пошти або іншого оператора.
  5. Координати. Місце на карті й точність визначення. OpenStreetMap може допомогти з географією; координата не є юридичним підтвердженням адреси.

Що перевірено в Нової пошти

2026-09-16 два запити Address.getSettlements і Address.getWarehouses повернули success=true та по два записи першої сторінки. У цих пробах apiKey був порожній. Для робочої інтеграції потрібно окремо перевірити режим доступу, ліміти та умови використання.

Записи містять власні Ref і координати. У точках обслуговування є CityRef, SettlementRef, тип, статус, графік і обмеження. Перевірена відповідь не доводить, що сервіс містить усі вулиці та будинки України.

Паспорт і приклад запиту →Результати проб · JSON →

Повні довідники перевізника не скопійовані та не оновлюються в Ладі. Пошук вулиць і будинків ще потребує окремої перевірки.

Власна адреса та зовнішні відповідності

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

Адреса
Країна, територіальний код, вулиця, будинок, корпус, приміщення, поштовий індекс.
Джерело
Оригінальний текст і структурована відповідь, назви видавця, версія, дата.
Відповідності
ЄДРА ID, ID Укрпошти, Nova Poshta SettlementRef / CityRef. Порожнє значення означає відсутню відповідність.
Доставка
Перевізник, спосіб, ID точки, поточний статус та обмеження. Це окремий запис від адреси.
Якість
Підтверджено, запропоновано, конфлікт або не перевірено; підстава та автор рішення.

Будинок «12-А», корпус «2» і приміщення «15» зберігайте текстовими компонентами. Синоніми та скорочення допомагають пошуку, але не визначають тотожності адрес. Одного збігу рядка недостатньо для автоматичного об’єднання.

Приклад моделі · JSON ↓

Навчальний приклад структури. Адресний редактор, персональні адреси та автоматичне зіставлення не реалізовані.

Як це працює у формі

  1. Людина обирає країну й населений пункт; система зберігає ID та джерело.
  2. Для доставки перевізником система знаходить відповідний населений пункт у його довіднику. Неоднозначний збіг потребує вибору.
  3. Для відділення людина обирає точку за типом, розташуванням і обмеженнями. Для кур’єра вводить адресу з доступними підказками.
  4. Перед відправленням система перевіряє доступність обраної послуги та точки. У документі залишається адреса, використана на той момент.

Якщо в довіднику немає адреси, дозволяйте зберегти введений текст зі статусом «не перевірено». Подальше зіставлення не повинно непомітно змінювати вже оформлений документ.

Оновлення й винятки

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

Як зберігати власні назви та офіційні версії →