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

# BlackBox

BlackBox — база покупців, які замовляють і не забирають посилки. Інтеграція сама перевіряє кожну угоду за телефоном і показує результат смугою в картці угоди (там само «Перевірити ще раз»), а покупця, що не забрав посилку, можна самому додати в базу з угоди. Запити до BlackBox лімітовані, тому залишок на сьогодні видно в картці.

## Можливості
- Автоперевірка кожної угоди (з сайтів, Prom, Rozetka, Епіцентру, OLX, вручну) за телефоном: нова — одразу, а пропущені (телефон додали пізніше, BlackBox не відповів) — фоном протягом 5 хвилин.
- Вікно «за останні N днів» — щоб старі угоди з імпорту не витратили денний ліміт.
- Смуга в угоді: «покупця в базі нема», «покупця знайдено в базі несумлінних» з деталями, «перевірка в черзі», «не вдалося перевірити» з причиною, «у угоді нема телефону».
- «Перевірити ще раз» у смузі та в «⋮» угоди — навіть коли автоперевірку вимкнено.
- Стан угод у налаштуваннях: скільки перевірено, знайдено, чекає, без телефону.
- «Додати в BlackBox» з угоди: ТТН і телефон з доставки, коментар обов'язковий.
- Історія перевірок і залишок запитів на сьогодні.

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

1. «Підключення» → «API ключ» → «Ввести» → «Зберегти ключ». Ключ — у вашому кабінеті BlackBox. Зберігається зашифрованим. Перевірки кнопкою нема: запити платні, тож дивіться стан ключа й журнал.
2. Вкладка «Перевірки» → «Перевірка покупців» → «Автоматична перевірка»: «Увімкнено» / «Вимкнено». Перемикач показує, чи перевірка справді працює. Увімкнули його — вмикається й перемикач «Інтеграція» у вкладці «Підключення» (це той самий головний вимикач; вимкнули «Інтеграцію» — автоперевірка зупиняється). Підказка під перемикачем каже, чого бракує: «Спершу введіть API ключ BlackBox у вкладці «Підключення».», «Інтеграцію вимкнено у вкладці «Підключення». Увімкніть перемикач тут — запрацює й картка.» або «Працює.».
3. «Які угоди» → «за останні … дн.» → «Зберегти». Типово 7 днів, можна від 1 до 90. Перевіряються відкриті угоди (не в архіві, без «Виграно»/«Програно»), оформлені за ці дні.
4. «Стан угод» — за вікном: «перевірено X з Y», «знайдено в базі», «чекають перевірки», «не вдалося», «без телефону».
5. «Залишок запитів» — на сьогодні, за останньою відповіддю BlackBox.

## 2. Автоматична перевірка кожної угоди
Коли «Автоматична перевірка» увімкнена:
- нова угода перевіряється одразу у фоні (за кілька секунд після створення);
- кожні 5 хвилин CRM дочищає решту: відкриті угоди з вікна «за останні N днів», які ще не перевірено, — наприклад, телефон додали пізніше або BlackBox тоді не відповів. За раз — до 20 угод, найновіші першими;
- якщо перевірка не вдалася, причина записується в угоду, а повтор буде не раніше ніж за годину. Коли денний ліміт BlackBox вичерпано, дочищення чекає наступної доби.

Номер береться з доставки угоди (отримувач), інакше — головний телефон клієнта. Перевірка йде через збережений результат (14 днів): той самий номер не витрачає запит удруге.

Результат — у смузі під етапами в картці угоди, у додаткових полях угоди (блок «BlackBox») і в журналі угоди (підпис «BlackBox»).

## 3. Перевірити вручну з угоди
Смуга BlackBox під етапами в картці угоди:
| Смуга | Що означає | Кнопка |
| --- | --- | --- |
| «BlackBox: покупця в базі нема» (зелена) | Перевірено, у базі нема | «Перевірити ще раз» |
| «BlackBox: покупця знайдено в базі несумлінних» (червона) | Знайдено; «Детальніше» / «Сховати» — інциденти | «Перевірити ще раз» |
| «BlackBox: перевірка в черзі» | Автоперевірка візьме угоду сама протягом кількох хвилин; смуга оновиться без перезавантаження | «Перевірити зараз» |
| «BlackBox: не вдалося перевірити» | Причина й час останньої спроби; повтор автоматично | «Перевірити ще раз» |
| «BlackBox: ще не перевірено» | Автоперевірку вимкнено або угода поза вікном днів | «Перевірити» |
| «BlackBox: у угоді нема телефону — перевірити не можна» | Нема номера ні в доставці, ні в клієнта | — |

Те саме — «⋮» → «Перевірити в BlackBox». Ручна перевірка йде повз збережений результат і витрачає запит.

## 4. Додати покупця в BlackBox
1. Картка угоди → «⋮» → «Додати в BlackBox».
2. Шторка «Додати в BlackBox»: номер ТТН і телефон беруться з доставки угоди; «Що сталося (обов'язково)» — опис, його бачать інші продавці.
3. «Додати в базу».

Масово додати не можна — коментар потрібен до кожного покупця.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Не задано BLACKBOX_API_KEY — введіть ключ BlackBox у картці інтеграції» | Ключ не введено | «Підключення» → «API ключ» |
| «У угоді нема телефону — BlackBox перевіряє лише за номером» | Нема телефону | Додайте телефон клієнта |
| «Опишіть, що сталося (коментар обов'язковий — його бачать інші продавці)» | Порожній коментар | Заповніть «Що сталося» |
| «У угоді нема ТТН — BlackBox приймає покупця лише з номером відправлення» | Немає ТТН у доставці | Додайте ТТН |
| «Нема телефону отримувача» | У доставці нема телефону | Заповніть телефон у доставці |
| «BlackBox: …» / «BlackBox не відповів: …» | Помилка або недоступність сервісу | Повторіть пізніше; перевірте залишок запитів |
| Смуга «BlackBox: не вдалося перевірити» | Автоперевірка не отримала відповіді | Нічого: повтор автоматично за годину; або «Перевірити ще раз» |
| «Автоматична перевірка» не вмикається | Ви не адміністратор | Попросіть адміністратора |
| «Чекають перевірки» не зменшується | Вичерпано денний ліміт або нема ключа | Дивіться «Залишок запитів» і журнал картки |

## Для ШІ-співробітників
- `deals_blackbox(deal_id)` — результат угоди: `checked`, `checked_at`, `found`, `detail`, `phone`, `queued` (перевіриться сама), `error` і `tried_at` (чому не вдалася автоперевірка).
- `deals_blackbox_check(deal_id)` — «Перевірити ще раз» (повз збережений результат, витрачає запит денного ліміту); результат і підпис ШІ — у смузі й журналі угоди.
- Те саме видно в додаткових полях угоди (`blackbox_*`) через `deals_get`: ШІ може попередити людину перед відправкою з накладним платежем.
- Налаштування автоперевірки (`/api/crm/blackbox/settings`) змінює лише адміністратор — інструментів для них у ШІ нема.

Статтю ШІ читає інструментом `help("int-blackbox")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [SMS (TurboSMS)](int-sms.md).