> Усі статті WIKI Helomi: /wiki/llms.txt

# Нова Пошта

Інтеграція з Новою Поштою дає створювати ТТН прямо з угоди, друкувати стікери, бачити статус посилки й автоматично переводити угоду на етап за статусом доставки. Налаштування повторюють KeepinCRM: що писати в ТТН, скільки місць і які габарити, кілька відправників (акаунтів) зі своїми ключами й доступами, зв'язок статусів і полів угоди.

## Можливості
- Створення ТТН з картки угоди: шторка «Створити ТТН» з даними угоди й дефолтами акаунта; «Додати ТТН» — записати наявний номер.
- Кілька акаунтів-відправників, у кожного свій ключ API, відправник, дефолти форми і список людей з доступом.
- «Додаткова інформація», внутрішній номер, супровідні документи, тип отримання грошей, кількість місць і габарити — за налаштуваннями.
- «Пов'язані статуси»: статус відправлення → етап угоди; окремо — з огляду на тип оплати.
- «Пов'язані поля»: з яких полів угоди брати місто, відділення, одержувача й телефон.
- Довідник міст і відділень Нової Пошти у формі.
- Автоматична ТТН на етапі угоди — у налаштуваннях каналу продажів (Prom, Rozetka, сайти…).

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Нова Пошта». Картка одразу відкриває вкладку «Налаштування»; поруч — «Підключення».

1. **Ключ.** Найпростіше — у «Налаштування» → «Акаунти» (розділ 2): кожен акаунт має свій «API ключ». Ключ береться в особистому кабінеті: my.novaposhta.ua → Налаштування → Безпека. У «Підключенні» є ще загальний «API ключ» картки — він діє, коли акаунтів нема.
2. **Перевірка.** «Перевірити» (у «Підключенні» або в картці акаунта) читає довідник відправників; успіх — «відправник: <назва>». У картці акаунта перевірка ще й підставляє знайденого відправника в порожні поля.
3. **Увімкнення.** Блок «Інтеграція» → «Увімкнути інтеграцію»: створювати ТТН і трекати відправлення цієї служби з угод.
4. **Зберегти.** Унизу липка панель «Скасувати зміни» / «Зберегти»; стан «Є незбережені зміни» / «Змін немає». Зберігати може лише адміністратор. Ключ акаунта зберігається окремо одразу кнопкою «Зберегти ключ».

Ключі зберігаються зашифрованими і назад не показуються — лише «задано (••••ca93)».

## 2. Акаунти відправників і доступи
1. «Акаунти» → «+ Додати акаунт» → «Назва акаунта (як підписати відправника)» → «Додати». Незбережені зміни сторінки перед цим зберігаються.
2. Натисніть рядок акаунта — він розгорнеться: перемикач «Увімкнено», «Перевірити», «Прибрати акаунт».
3. Групи полів акаунта:
   - «Акаунт» — «Назва»: як підписати відправника у списку акаунтів і формі ТТН (можна змінити будь-коли, потім «Зберегти»);
   - «Доступ до API» — «API ключ»;
   - «Відправник» — «Відправник» і «ПІБ відправника» вибираються зі списку кабінету Нової Пошти (список підтягується ключем акаунта сам, кнопка «Оновити список»; обрали ПІБ — «Телефон» підставляється), «Телефон», «Місто» (з довідника Нової Пошти), «Відділення відправки». Поки ключа нема або Нова Пошта не відповідає — поля вписуються вручну, під ними підказка чому;
   - «Відправлення за замовчуванням» — «Метод доставки» (Відділення-Відділення, Відділення-Двері, Двері-Відділення, Двері-Двері), «Тип вантажу», «Платник доставки», «Платник комісії за післяплату», «Опис вантажу», «Номер пакування», «Форма оплати», «Контроль оплати»;
   - «Додаткова інформація» — що писати у внутрішній номер ТТН саме цього відправника: «Як у налаштуваннях картки», «Не заповнювати внутрішній номер відправлення», «Розмістити ID угоди…», «Розмістити назву угоди…», «Розмістити інформацію з поля товару…»;
   - «Розмір і вага відправлення» — довжина, ширина, висота, загальна вага, «Загальний об'єм (м³)» (0 — рахується з габаритів).
4. **Доступи.** Блок «Доступи · <акаунт>»: після додавання акаунта доступу нема ні в кого. Поставте «Показати» тим, хто створює ТТН цим відправником. Без галочки акаунта не видно у формі ТТН; адміністратор бачить усі. ШІ-співробітники в списку позначені «ШІ».
5. «Прибрати акаунт» — ключі й дефолти форми зникають, угоди лишаються.

У рядку акаунта видно стан: «без ключа», «увімкнено» або «вимкнено».

## 3. Що писати в ТТН: додаткова інформація, місця, габарити
- «Додаткова інформація»: «Без автогенерації», «Назва товару», «Артикул і кількість», «Назва товару і кількість» або «Шаблон» (доступні `{deal.title}`, `{deal.id}`, `{items}`).
- «Внутрішній номер відправлення»: «Не заповнювати», «ID угоди», «Назва угоди» або «Поле товару». Акаунт може мати свій вибір («Додаткова інформація» в акаунті, розділ 2) — він головніший.
- «Супроводжуючі документи»: текст.
- «Тип отримання грошей» за замовчуванням: «Без зворотної доставки» або «У відділенні» (пов'язане поле угоди, розділ 4, головніше).
- «Кількість місць»: «На основі кількості товарів», «Фіксована кількість» або «З поля товару».
- «Вага й габарити з товарів»: галочка «Заповнювати вагу й габарити посилки з товарів угоди» — посилка рахується з товарів угоди й кількості, а не з акаунта ([Доставки і ТТН, 3а](shipping.md#3а-вага-й-габарити-з-товарів-угоди)).
- «Розмір відправлення»: «Загальні параметри відправлення» або «Заповнити кожне місце окремо»; галочки «Увімкнути параметри відправлень для вибору» (у формі ТТН — список збережених габаритів) і «Заповнити контроль оплати, якщо без зворотної доставки».

## 4. Пов'язані поля угоди
Блок «Пов'язані поля»: з яких полів угоди брати «Місто», «Відділення», «Одержувач», «Телефон» у форму ТТН (наприклад, з полів замовлення Prom чи Rozetka). Порожньо — з клієнта й адреси доставки угоди. Якщо в «Місто» чи «Відділення» обрано поле з повною адресою (наприклад, «Адреса доставки (prom)» — «Київ, Відділення №25 (до 30 кг): вул. …»), у форму йдуть розібрані місто й № відділення, а не весь рядок; адреса без номера відділення поле не заповнює. Поле може містити всю адресу маркетплейсу — як «Адреса доставки (prom)»: «м. Черкаси (Черкаська обл.), №7 (до 30 кг на одне місце): вул. Петра Дорошенка, 7». Тоді в «Місто» йде лише місто («Черкаси», з областю для вибору зі списку), у «Відділення» — номер («7»), і шторка одразу вибирає їх зі списку Нової Пошти. Так налаштовано й типово (як у KeepinCRM): «Місто» і «Відділення» ← «Адреса доставки (prom)». «Тип отримання грошей» — поле-список угоди і таблиця «Значення для типу отримання грошей» → «Тип оплати» (Без зворотної доставки / У відділенні / Накладений платіж), «+ Додати».

## 5. Статус доставки → етап угоди
- «Пов'язані статуси»: «Зовнішній статус» → «Етап» (наприклад, «Відправлення отримано» → «Виграно», «Відмова» → «Повернення»). Без рядка етап не змінюється. Статуси Нової Пошти з датою підтримують шаблони та «починається з». Тексти зі списку (з довідки API НП) зіставляються за **кодом статусу**: НП пише інакше («Прибув у відділення», «Відправлення прямує до м. Фастів.»), і рядок «Прибув на відділення» чи «Відправлення прямує до міста YYYY.» спрацьовує саме за кодом. Назви з KeepinCRM («Отримано», «Прибуло у відділення», «Відмова») теж спрацьовують — під рядком видно, на які статуси НП; рядок без відповідника позначено.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- Той самий статус можна зв'язати з етапами різних воронок, як у KeepinCRM: «Відправлення отримано» → «Отримано [Продажі]» і → «Отримано Покупцем [Дропшипери продаж]». Угода переходить на етап своєї воронки. Якщо статус зв'язаний лише з етапами інших воронок (кількох) — угода не рухається. Двічі той самий статус з тим самим етапом — помилка «… з тим самим етапом вказано двічі».
- «Пов'язані типи оплат та статуси»: те саме з огляду на тип оплати («Накладений платіж» + «Відправлення отримано» → «Виграно»). Ці рядки головніші. Рядок можна лишити без етапу — тоді для цього статусу діють звичайні «Пов'язані статуси».

Етап змінюється, коли оновлюється статус ТТН — кнопкою «Оновити статус» у «⋮» рядка ТТН в угоді. Архівні угоди не рухаються; у журналі угоди автор — «трекінг доставки».

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються.

## 6. Створити ТТН з угоди
Картка угоди → блок «Доставка» → «+» → шторка «Створити ТТН» → вкладка «Нова Пошта» → акаунт відправника → перевірте отримувача, місто, відділення, оплату й місця → «Створити ТТН». Режим «Додати ТТН» записує вже наявний номер. Покроково — стаття [Доставки і ТТН](shipping.md).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): NP_API_KEY» | Ключ не введено | Введіть «API ключ» в акаунті або в «Підключенні» |
| Помилка Нової Пошти після «Перевірити» | Ключ недійсний | Створіть новий ключ у my.novaposhta.ua |
| «Нема доступу до акаунта «…» Нова Пошта — надайте його в картці перевізника → …» | Людині не поставлено «Показати» в «Доступах» | Адміністратор ставить галочку |
| «Акаунт «…» вимкнено в налаштуваннях Нова Пошта» | Перемикач акаунта вимкнено | Увімкніть акаунт |
| «Вкажіть назву акаунта» | Порожня назва при додаванні | Введіть назву |
| «Телефон отримувача «…» — потрібен формат +380XXXXXXXXX» | Неправильний телефон у формі ТТН | Виправте телефон |
| «Не вказано місто отримувача» / «Не вказано отримувача (ПІБ)» | Немає даних у формі | Заповніть або налаштуйте «Пов'язані поля» |
| «Кількість місць: від 1 до 50» | Завелике число | Вкажіть менше |
| «Список з Нової Пошти недоступний: …» під «Відправником» | Ключ акаунта не збережено або Нова Пошта його відхилила | Збережіть «API ключ», «Перевірити», «Оновити список»; або впишіть відправника вручну |
| «Пов'язані статуси: статус «…» з тим самим етапом вказано двічі» | Повтор рядка | Приберіть зайвий рядок |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). Відправників ключем акаунта ШІ бачить через `integrations_carrier_np_senders`. ТТН створює людина. ШІ бачить доставки угоди в `deals_get` (служба, ТТН, статус) і може отримати доступ до акаунта відправника (рядок «ШІ» в «Доступах») на майбутнє. Статтю ШІ читає інструментом `help("int-nova-poshta")`.

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Угоди](deals.md), [Укрпошта](int-ukrposhta.md), [Meest](int-meest.md), [Rozetka Delivery](int-rozetka-delivery.md).