← Повернутися до блогу
/AI-автоматизація/4 хв читання

Нова пошта API інтеграція: сповіщення про статус ТТН у Telegram

Нова пошта API інтеграція без розробника: налаштовуємо сповіщення про статус ТТН у Telegram за 4 вузли n8n, ключ до API — 0 грн.

Нова поштаAPIn8nTelegramавтоматизація

Клієнт пише «де моя посилка?» — менеджер відкриває трекінг, копіює статус, відповідає в чат. На десятку замовлень це пів години на день. На сотні — окрема людина, яка тільки тим і займається. Нова пошта дає безплатний API, що віддає статус будь-якої ТТН. Лишається опитувати його раз на пів години і слати зміну статусу в Telegram — клієнту або вашому менеджеру. Зберемо це в n8n за чотири вузли.

Що дає API Нової пошти

Ключ генерується в бізнес-кабінеті: Налаштування → Безпека → «Створити ключ». Це безплатно. Після цього у вас є точка входу https://api.novaposhta.ua/v2.0/json/ і доступ до моделі TrackingDocument з методом getStatusDocuments — саме він віддає розширений статус посилки.

Запит виглядає так:

{
  "apiKey": "ВАШ_КЛЮЧ",
  "modelName": "TrackingDocument",
  "calledMethod": "getStatusDocuments",
  "methodProperties": {
    "Documents": [
      { "DocumentNumber": "20450123456789", "Phone": "380501234567" }
    ]
  }
}

DocumentNumber — номер ТТН. Phone — телефон відправника. Поле необов'язкове, але без нього API віддає менше даних: частина статусів закрита. У відповіді в data[0] лежать StatusCode (число), Status (текст українською) і ScheduledDeliveryDate — планова дата доставки. Для сповіщення вистачає перших двох.

Чотири вузли в n8n

  1. Schedule Trigger — раз на 30 хвилин.
  2. HTTP Request — метод POST, URL точки входу, body — JSON вище.
  3. Code — прочитати StatusCode, зібрати повідомлення.
  4. Telegram — надіслати в чат.

Код третього вузла, спрощений:

const items = $input.all()[0].json;
const statuses = items.data || [];
const msg = statuses.map(s =>
  `📦 ${s.Number}: ${s.Status} (код ${s.StatusCode})`
).join("\n");
return [{ json: { text: msg } }];

Цього вистачає, щоб побачити статус у чаті. Якщо ж слати повідомлення на кожен прогін, ви отримаєте 48 однакових «Відправлення в дорозі» на добу. Тому наступний крок — не новий вузол, а логіка.

Підводний камінь: дедуплікація

API не каже «статус змінився» — він просто віддає поточний. Різницю між «слати завжди» і «слати тільки зміну» робите ви. Найпростіший спосіб — тримати останній StatusCode для кожної ТТН у таблиці (Google Sheets або SQLite) і порівнювати перед відправкою. Без цього рішення спамить клієнта, і він його заблокує.

Другий камінь — телефон відправника. Якщо ви відправляєте від свого імені, телефон лежить у Phone вашого кабінету. Якщо замовлення везуть різні відправники, тримайте мапу «відправник → телефон», інакше частина ТТН віддасть неповний статус.

Третій — частота. 30 хвилин для сповіщень вистачає майже завжди. Але в сезон Нова пошта оновлює статуси нерівномірно, тож «прибуло у відділення» може прийти із запізненням на годину. Для «забрати сьогодні» ставте 15 хвилин, але не частіше — API без потреби смикати не варто.

Навіщо це, якщо є офіційний бот

У Нової пошти є власний трекінг і бот. Але він знає тільки про посилку, а не про ваше замовлення. Власна інтеграція дає змогу зібрати в одному повідомленні статус ТТН і дані з CRM: склад замовлення, суму, менеджера. Клієнт пише вашому боту, а не сторонньому сервісу, і ви не віддаєте контакт на бік.

Якщо ви ще не працювали з n8n, почніть із базового огляду — що це і скільки коштує, а потім зберіть свого Telegram-бота на n8n — там сам механізм підключення бота. Повний перелік того, що ми автоматизуємо, — на сторінці послуг.

Чек-лист запуску

  1. Згенеруйте API-ключ у бізнес-кабінеті (Налаштування → Безпека).
  2. Перевірте запит вручну через Postman або curl на одній ТТН — подивіться, які поля реально приходять.
  3. Вкажіть Phone відправника, щоб статуси були повними.
  4. Додайте зберігання останнього StatusCode і відправку лише на зміну.
  5. Поставте інтервал 15–30 хвилин залежно від навантаження.
  6. Проженіть на 5–10 тестових ТТН з різними статусами, перш ніж пускати на бойових клієнтів.

Стартовий шлях — саме цей, із чотирьох вузлів. Далі природно додаються: бот, який приймає номер ТТН від клієнта і сам повертає статус; сповіщення менеджеру про «повернення» або «не забрали з відділення» за два дні до кінця терміну зберігання; відмітка в CRM, що посилку отримано.

Якщо хочете, щоб це працювало без вашого втручання з першого дня — напишіть нам, зберемо ланцюжок від пошуку ТТН до повідомлення в Telegram за кілька днів.

Ірина, Співзасновниця · продажі та клієнтиОлександр, Співзасновник · технічна експертиза

Команда AIRINEX

← Усі статті