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

# Meest

Інтеграція з Meest створює відправлення з угоди, друкує стікери, відстежує посилки й переводить угоду на етап за статусом доставки. Налаштування — як у KeepinCRM: кілька акаунтів-відправників зі своїм договором і токеном, дефолти форми ТТН, доступи, зв'язок статусів і полів угоди.

## Можливості
- Відправлення у відділення або поштомат з обох сторін, післяплата на розрахунковий рахунок.
- Кілька акаунтів-відправників, у кожного свій договір, токен, відправник і доступи.
- «Додаткова інформація» і «Номер замовлення» в ТТН за налаштуваннями.
- «Пов'язані статуси» і «Пов'язані типи оплат та статуси» → етап угоди.
- «Пов'язані поля»: місто, відділення, одержувач, телефон з полів угоди.

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

1. **Ключі.** «Contract ID» береться з договору з Meest, «Токен» — від Meest. Вводяться в акаунті (розділ 2) або в «Підключенні» («API токен», «ID договору») — останні діють, коли акаунтів нема. Зберігаються зашифрованими.
2. **Перевірка.** «Перевірити» в «Підключенні»: «токен прийнято» або «авторизація за логіном пройшла». «Перевірити» в картці акаунта перевіряє все, без чого ТТН не створиться: токен, «Contract ID» (заданий і має вигляд коду договору Meest) і відділення відправника в довіднику Meest. Успіх — «токен і Contract ID прийнято; відділення відправника: №1354: вул. …»; якщо прихований код відділення веде не на той №, що в полі «Відділення відправки», перевірка це скаже.
3. **Налаштування.** «Інтеграція» («Увімкнути інтеграцію»), «Додаткова інформація», «Номер замовлення» (не заповнювати, ID угоди, назва угоди), «Акаунти», «Доступи», «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», «Вага й габарити з товарів» (галочка: вага й розмір посилки — з товарів угоди й кількості, а не з акаунта; [докладно](shipping.md#3а-вага-й-габарити-з-товарів-угоди)). Унизу — «Скасувати зміни» / «Зберегти».

## 2. Акаунти і доступи
«Акаунти» → «+ Додати акаунт» → назва → «Додати». Розгорнутий акаунт: «Увімкнено», «Перевірити», «Прибрати акаунт» і групи:
- «Відправник»: «Ім'я відправника», «Contract ID», «Токен», «Метод доставки відправника» і «Метод доставки отримувача» (Відділення / Поштомат; Meest приймає поштомат як відділення — його обирають у списку відділень), «ЄДРПОУ», «Телефон»;
- «Відправлення за замовчуванням»: «Платник доставки», «Місто» (зі списку Meest — почніть вводити назву), «Відділення відправки» (зі списку Meest міста; можна ввести №), «Форма оплати» (Готівка / Безготівка), «Післяплата» (На розрахунковий рахунок; зарахування на картку не дозволено);
- «Розмір і вага відправлення» — діють і для ТТН, які створює автоматика (Олесь, ШІ), коли в заявці розмірів нема; вага з карток товарів головніша.

Список міст і відділень з'являється, коли в акаунті збережено «Токен». Відділення, вибране зі списку, запам'ятовує свій код у Meest (під полем — «вибрано зі списку Meest»). Ручне введення або зміна міста цей код скидає — тоді відділення шукається за містом і №; опис із KeepinCRM («Партнерське №1354, посилки до 30кг… 108/1») теж працює — береться №1354.

«Доступи · <акаунт>»: «Показати» тим, хто створює ТТН цим відправником, і ШІ-співробітникам, які оформлюють замовлення (Олесь). Новий акаунт одразу відкритий тому, хто його додав. Без галочки акаунта не видно у формі; адміністратор бачить усі. Акаунт, відкритий нікому, картка позначає жовтим «нікому не відкрито».

**Що картка каже сама.** Над полями акаунта — «Щоб створювати ТТН, бракує: «Contract ID», місто й відділення відправника…» (поки чогось нема). Після «Зберегти» зі зміненим містом чи відділенням відправника «Перевірити» запускається саме, і помилку («відділення №… не знайдено») видно одразу в картці, а не при створенні ТТН.

**Без налаштувань сервера.** Усе для роботи — у картці: ключі, відправник, доступи, статуси. У новій організації ключі й відправник із налаштувань сервера не підставляються: поки акаунта нема, форма ТТН каже «додайте акаунт у «Інтеграції → Meest»». Стікер, трекінг і довідники міст/відділень ідуть ключем акаунта.

## 3. Статуси, типи оплат і поля угоди
- «Пов'язані статуси»: статус відправлення → етап угоди (без рядка етап не змінюється). **Статус має збігатися з текстом Meest дослівно** (великі й малі літери, апостроф і зайві пробіли не важать) — беріть зі списку. Meest надсилає: «Відправлення створено, але не передано на доставку», «Відправлення прийнято до перевезення», «Відправлення в дорозі», «Прибуття у транзитний сортувальний центр», «Відправлення з транзитного сортувального центру», «Відправлення прибуло в сортувальний центр», «Відправлення видане кур’єру і прямує у підрозділ отримання», «Надходження на підрозділ доручення», «Доручено», «Відправлення отримане», «Відправлення доставлене», «Прибуло на підрозділ повернення», «Відправлення повернуто відправнику», «Відправлення готове до видачі відправнику». Назви з KeepinCRM («Отримано», «Надійшло у відділення», «Оформлено для відправки», «Видано кур'єру»…) Meest не надсилає, але картка знає відповідники: «Отримано» спрацьовує на «Відправлення отримане», «Доручено» і «Відправлення доставлене», «Надійшло у відділення» — на «Надходження на підрозділ доручення»; під рядком написано, на що саме. Рядок, якому відповідника нема, позначено «такого тексту служба не надсилала». У випадайці — лише тексти, які Meest справді надсилала. Рядок із назвою KeepinCRM і рядок зі справжнім текстом можна мати обидва — збереження це не ламає.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- «Пов'язані типи оплат та статуси»: з огляду на тип оплати; головніші.
- «Пов'язані поля»: «Місто», «Відділення», «Одержувач», «Телефон», «Тип отримання грошей». Поле з повною адресою (наприклад, «Адреса доставки (prom)») розбирається: у форму йдуть місто й № відділення, а не весь рядок.

**Звідки статус.** Meest через API віддає історію лише відправлень вашого договору (токен акаунта). ТТН, які створив маркетплейс під своїм договором («Meest ПОШТА» на Prom, Rozetka, Епіцентр, OLX), Meest так не показує (аудит 15.10: з 51 ТТН Meest в угодах історію дали 2 — обидві вашого договору). Для угод Prom статус береться із замовлення Prom («Доставлено (Prom)», «Повернення (Prom)»…; лише коли номер декларації в замовленні — саме ця ТТН), і отримана посилка так само веде угоду у «Виграно» й архів. ТТН Rozetka, Епіцентру й OLX під їхнім договором поки бачить лише дзеркало KeepinCRM.

Етап змінюється, коли оновлюється статус ТТН (кнопка «Оновити статус» у «⋮» рядка ТТН; уточнити: чи є автоматичне періодичне оновлення).

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

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

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): MEEST_API_TOKEN, MEEST_CONTRACT_ID» | Ключі не введено | Введіть ключі в акаунті або в «Підключенні» |
| «токен відхилено (HTTP 401)» | Meest не прийняв токен | Перевірте токен |
| «токен прийнято, але не задано Contract ID» / «Contract ID не схожий на код договору Meest» | Немає або хибний код договору | Введіть «Contract ID» з договору Meest (вигляд xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) |
| «… відділення №… у місті «…» не знайдено в довіднику Meest» / «прихований branch_id веде на відділення №…» | Відділення відправника введено текстом або змінено без вибору зі списку | Оберіть місто й відділення відправника зі списку Meest, «Зберегти», «Перевірити» |
| «Meest: не визначив відділення відправника» під час створення ТТН | Те саме | Те саме |
| Статус ТТН змінюється, а етап угоди — ні | Текст у «Пов'язаних статусах» не збігається з текстом Meest | Оберіть статус зі списку (розділ 3) |
| «Вкажіть № відділення/поштомата … або адресу доставки» | У формі нема відділення | Заповніть відділення або «Пов'язані поля» |
| «Нема доступу до акаунта «…» Meest — …» | Не поставлено «Показати» | Адміністратор дає доступ |
| «Акаунт «…» вимкнено в налаштуваннях Meest» | Акаунт вимкнено | Увімкніть акаунт |

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

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Нова Пошта](int-nova-poshta.md), [Укрпошта](int-ukrposhta.md).