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

# Фіскальні чеки Checkbox

Фіскальний чек створюється з угоди через інтеграцію Checkbox (ПРРО). У картці угоди чеки лежать у блоці «Документи» тими самими рядками, що й документи: знак «C», «Продаж (NovaPay)» або «Повернення (…)», фіскальний номер, стан, сума, дата, касир. Усі чеки організації — «Фінанси → Фіскальні чеки».

## Підключення каси: два кроки

Крок 1 — «Підключення каси» у профілі, усе на одній сторінці по порядку: 1) ключ ліцензії справжньої каси (кабінет Checkbox → «Каси»); 2) як входить касир — ПІН-код касира або логін і пароль касира (кабінет Checkbox → «Касири»; email і пароль від кабінету не підходять); 3) «Підключити касу» — перевіряє вхід, підтягує ПІБ з Checkbox, сам створює першого касира і вмикає інтеграцію. Після цього в «+» блоку «Документи» угоди з'являється «Фіскальний чек».

Крок 2 — касири, лише якщо їх кілька: «Додати касира» → ПІБ і спосіб входу: обліковий запис каси (нічого не вводити), ПІН-код (ключ ліцензії береться з каси) або свій логін/пароль. «Авторизація» підтягує ПІБ.

**Тестова й справжня каса.** У кабінеті Checkbox є «Тестові дані»: тестова каса зі своїм ключем ліцензії і тестовий касир, чиї чеки не йдуть до ДПС. Їх не можна змішувати: справжній касир з ключем тестової каси (або навпаки) дає відмову «Реальний касир не може працювати з тестовою касою». Для реальних чеків беріть ключ ліцензії справжньої каси («Каси») і справжнього касира («Касири»); для проби — і касу, і касира з «Тестових даних».

## Каса на кожну юрособу

У «Інтеграції → Checkbox» кожна організація (профіль) — це каса з касирами, доступами, пов'язаними полями й мапою способів оплати. У профілі є поле **«Юрособа»**: угоди цієї юрособи пробиваються саме цією касою. Юрособу угоди визначає її поле «Юрособа» або правила «звідки угода → юрособа» («Налаштування → Бренди та юрособи»): канал, джерело, бренд, воронка, папка складу. Одна юрособа — один профіль. Профіль без юрособи — «загальна каса» для угод, у яких своєї каси нема.

У картці угоди над документами показано, хто пробиває: «Чек пробиває: ФОП … · за правилом · каса …». Якщо для юрособи касу не налаштовано, система про це каже і просить обрати касу вручну.

## Створити чек

Номер угоди потрапляє в підвал чека рядком «Замовлення <номер>» (вмикається в профілі каси: «Номер угоди в підвалі чека», типово так); окремого поля для номера замовлення в Checkbox нема.

У блоці «Документи» угоди «+» → перший пункт **«Фіскальний чек: касир»** — чек створюється одразу: усі позиції угоди, каса за юрособою, тип оплати з поля угоди «Тип оплати checkbox» (значення → Готівка / Картка / своя назва безготівки за мапою профілю), email клієнта (якщо ввімкнено «Відправка Email»). Якщо зміну в Checkbox не відкрито — CRM відкриває її сама ключем ліцензії каси (налаштування профілю «Відкривати зміну автоматично, коли створюється чек», увімкнено типово; вимкнете — перед чеком спитає «Відкрити зміну?»). Якщо типу оплати в угоді нема або каси для юрособи нема — відкривається шторка, де їх можна вибрати.

**«Тип оплати checkbox» заповнюється сам**, коли замовлення приходить з площадки, і лише якщо поле порожнє (вибір людини не змінюється). Правила власника: Rozetkapay — оплата через Пром або Розетку (Пром-оплата, частинами, Google/Apple Pay, картка, накладений платіж Розетка Делівері); NovaPay — накладений платіж Новою поштою; UAPay — OLX-доставка; Карта — переказ на карту; Розрахунковий рахунок — оплата на рахунок; Готівка — готівкою; усе інше — Інтернет-еквайринг. Ручне поле «Спосіб оплати» головніше за дані площадки. Якщо про оплату ще нічого не відомо, поле лишається порожнім. Колонка «Тип оплати» у списку угод показує саме це значення (текст площадки, наприклад «Пром-оплата», — у полях маркетплейсу в картці).

Для ШІ: `checkbox_receipt_create(deal_id, values={profile_id?, payment_value?, emails?, comment?, open_shift?})`. Зміна відкривається сама; відповідь 409 з кодом `no_shift` буває лише коли в профілі вимкнено автоматичне відкриття — тоді повторити з `open_shift=true`; 409 `duplicate` — по угоді вже є чинний чек; 400 `no_payment` — вкажіть `payment_value` зі списку `payment_options` з `checkbox_deal(deal_id)`.

Архів не заважає: угода на етапі «Отримано» сама йде в архів як виграна, і саме її фіскалізують — і вручну через «+», і автоматичним чеком. Захищає лише правило «один чинний чек на угоду».

## Назва товару в чеку

Назва в чеку має бути одна на артикул, хоч би скільки оголошень із різними назвами було в прайс-листі. Тому в позиції прайс-листа є поле **«Назва Checkbox»**, яке склад передає в прайс-лист: воно само дорівнює назві пов'язаного товару складу і йде слідом, коли товар на складі перейменували. Його видно в картці позиції і колонкою в таблиці прайс-листа; за потреби можна вписати своє («= зі складу» повертає назву складу). У чек іде «Назва Checkbox» з прайс-листа. Угоди з каналів (Prom тощо) приходять з артикулом і товаром складу без посилання на позицію прайс-листа, тому CRM шукає її сама: позиція прайс-листа угоди → позиція з тим самим артикулом → позиція, пов'язана з тим самим товаром складу. Якщо «Назви Checkbox» ніде нема — назва товару складу, далі поле з налаштування профілю «Назва товару», далі назва позиції угоди.

## Фіскалізована угода

У списку угод фіскалізована угода має знак «C» біля назви, фільтр «Чек: усі / Фіскалізовані / Без чека» відбирає такі угоди. Для ШІ — параметр `fiscalized=1|0` у `deals_list`.

## Один чек на угоду

По угоді не може бути більше одного чинного чека продажу: поки попередній не повернуто, другий не створиться — ні людиною, ні ШІ, ні тригером. Позиції угоди, що в чеку, не редагуються. Щоб пробити заново — спершу «Повернути чек».

## Повернення, друк, посилання

Перегляд, PDF, PNG і текст чека CRM бере з публічних сторінок Checkbox без входу касира, тож вони працюють, навіть якщо вхід касира зламано.

«⋮» біля чека: Переглянути (вікно на весь екран: чек аркушем або текстом, кнопки «Checkbox» і «ДПС», закрити — «←» або Esc), Відкрити PDF, Скопіювати URL на чек (сторінка чека на сайті Checkbox, `https://check.checkbox.ua/<id чека>`), Друк TXT, Друк PNG, Повернути чек (чек повернення на той самий склад і суму; після нього угода знову вільна для чека), Відправити Email, Оновити стан (поки Checkbox ще не дав DONE).

Для ШІ: `checkbox_receipt_return(receipt_id)`, `checkbox_receipt_pdf(receipt_id, fmt=pdf|png)`, `checkbox_receipt_email(receipt_id, values={emails:[…]})`, `checkbox_receipt_refresh(receipt_id)`, `checkbox_receipts_list(q, kind, status, profile_id, date_from, date_to)`.

## Автоматичний чек (тригер)

«Налаштування → Тригери» має дію **«Фіскальний чек Checkbox»** поряд із Webhook: таблиця «Угоди» (або «Доставка»), умова, наприклад `stage.name == 'Отримано'`, і чек створюється сам, коли умова стала істинною — без людини. Каса — за юрособою угоди (або вказана в тригері), оплата — з поля угоди, зміна відкривається сама, якщо в профілі ввімкнено «Автоматичний чек відкриває зміну». Швидкий шлях — «Інтеграції → Checkbox → Автоматичний чек → Увімкнути чек при «Отримано»». Етап «Отримано» угода отримує від перевізника за «Пов'язаними статусами» в налаштуваннях Нової Пошти / Укрпошти / Meest.

Результат кожного спрацювання — у журналі тригера і нотаткою в угоді: «створено» (з номером чека), «пропущено» (чек уже є, угоду вже фіскалізовано в KeepinCRM, нема позицій) або «не створено» (нема типу оплати, каси, зміни, помилка Checkbox).

**Тригери «Отримано» і «Скасовано» в усіх воронках (15.10).** У «Налаштування → Тригери» стоять чотири тригери таблиці «Угоди», «Відразу». Кожен діє в усіх воронках одразу:
- «Чек Checkbox: замовлення отримано» — умова `stage.name == 'Отримано'`, «Автоматично відкривати зміну, якщо вона закрита». Діє і для угод, що прийшли з KeepinCRM та ще були в дорозі на 14.10. Якщо KeepinCRM уже пробила чек (у списку угод знак «C»), другий не створюється.
- «Завершити угоду: замовлення отримано» — «Завершити угоду» → «Виграно».
- «Завершити угоду: угоду скасовано» — умова `stage.role == 'lost'` (етап скасування будь-якої воронки) → «Програно».
- «Повернути чек: угоду скасовано» — умова `stage.role == 'lost' OR result == 'failed'` → «Повернути фіскалізований чек». Діє, лише якщо в угоді є чинний чек нашої каси; чек KeepinCRM повертають у KeepinCRM.

Тригери діють на нові переходи етапів: угоди, що вже стоять на «Отримано» чи скасовані, не чіпаються.

## Поля чека

`id`, `deal_id`, `kind` (sell / return), `status` (CREATED / DONE / ERROR / CANCELLED), `fiscal_code`, `fiscal_date`, `tax_url`, `total_amount`, `payment_type` (CASH / CASHLESS), `payment_label`, `payment_value`, `profile_name` (каса), `cashier_name`, `emails`, `item_ids`, `related_id` (у повернення — чек продажу), `returned_at` (у продажу — коли повернуто), `error`, `creator`, `created_at`.

## Контроль чеків

«Фінанси → Фіскальні чеки → Контроль» відповідає на питання власника «чи на всі угоди виписано чек»: за період і каналом — скільки отриманих угод потребують чека, у скількох він є (нашої каси чи ще KeepinCRM), скільки без чека і чому (автоматичний чек вимкнено, етап не в умові тригера, отримано до запуску тригера, помилка тригера чи Checkbox, чек повернено), скасовані з неповерненим чеком, кілька чеків на угоду, сума чеків проти виручки. «Виписати» звідти — той самий чек, що «+ → Фіскальний чек» у картці угоди. Тривога в «Фінанси → Огляд» щодня показує «N угод потребують уваги». Докладно — [Фінанси → Фіскальні чеки](finance.md#фіскальні-чеки); для ШІ — `checkbox_control`, `checkbox_control_issue`.