Фіскалізація (ПРРО)
FISCAL_MODE | Як працює | Коли обирати |
|---|---|---|
mono | Чек видає ПРРО, прив’язана в кабінеті plata by mono (власна ПРРО mono або Checkbox через mono). Місток передає в інвойс кошик з кодами товарів (code = SKU, barcode, групи податків MONO_TAX_CODES), забирає чек із fiscal-checks, кладе посилання в нотатку замовлення, тег fiscal-done, показує покупцю на Order status page і віддає PDF в адмінці (/admin/fiscal/:id.pdf). | усі онлайн-оплати йдуть через mono |
checkbox | Місток сам створює чек продажу у Checkbox після оплати (товари, доставка, CASHLESS), чек повернення при refund, а з CHECKBOX_FISCALIZE_ALL=true — і для інших замовлень при orders/paid (накладений → CASH). | кілька шлюзів, накладений платіж, одна каса на все |
vchasno | Вчасно.Каса (Orders API): після онлайн-оплати Місток створює замовлення з товарами (SKU, штрихкод, копійки) — каса видає чек одразу. Для накладеного платежу — відкладений чек: при відправці Місток передає ТТН Нової пошти / Укрпошти / Meest, а каса фіскалізує сама в момент, коли покупець платить у відділенні. Чеки повернення — вручну в застосунку каси (API їх не надає). | бухгалтер уже у Вчасно; багато накладених платежів; безкоштовний тариф до 300 чеків/міс |
none | нічого не фіскалізується | ФОП без ПРРО-обов’язку або зовнішня каса |
Чеки повернення через mono
Коли до mono прив’язана ПРРО, invoice/cancel обов’язково містить items — з них банк формує чек повернення. Місток бере позиції з вебхука Shopify refunds/create (refund_line_items + повернення доставки); якщо сума позицій не збігається з сумою повернення — одна підсумкова позиція на точну суму. Далі поллер читає fiscal-checks (type: return), записує посилання на чек повернення до нотатки замовлення й у журнал повернень. Те саме для часткового списання холду: invoice/finalize з items, якщо сума відрізняється.
| Подія | Виклик mono | Чек | Де видно |
|---|---|---|---|
| оплата success | — (ПРРО спрацьовує сама) | продаж (sale) | нотатка, тег, Order status, подія fiscalized, PDF в адмінці |
| refund у Shopify | invoice/cancel + items | повернення (return) | нотатка «Фіскальний чек повернення», журнал повернень |
| списання холду меншою сумою | invoice/finalize + items | продаж на нову суму | як для оплати |
чек failed | — | — | алерт власнику (Telegram/email), ручний повтор POST /admin/fiscal/:id/poll |
Накладений платіж
FISCAL_COD=false вимикає чеки для замовлень, оплачених через перевізника. Підстава: позиція Верховного Суду (справа 520/27700/25, червень 2026) щодо післяплати NovaPay як не розрахункової операції продавця. Це не юридична порада — узгодьте режим зі своїм бухгалтером; Місток лише дає перемикач і аудит-слід у нотатках замовлення.
Квитанції
SEND_MONO_RECEIPT=true — mono надсилає квитанцію про оплату на email покупця. Checkbox доставляє чек на email/телефон з полів delivery.
Вчасно.Каса: як працює відкладений чек
| Крок | Що робить Місток | Виклик |
|---|---|---|
| онлайн-оплата success | створює замовлення з типом оплати «картка», tag = mistok-<orderId> (ідемпотентно) | POST /api/v1/orders |
накладений платіж, orders/fulfilled з ТТН | створює відкладений чек: ТТН, перевізник (з tracking_company), товари, сума до сплати (мінус передоплата) | POST /api/v1/fiscal_links |
| поллер (кожні 10 хв, до 30 днів) | читає статус: 0/10/11 — чекаємо; 101 — чек є → нотатка, тег fiscal-done, подія fiscalized; 2000/2002 — скасовано/прострочено → алерт | GET /api/v1/fiscal_links/:id |
| refund у Shopify | повертає гроші в PSP і надсилає алерт «створіть чек повернення у Вчасно.Касі» | — |
Змінні: VCHASNO_TOKEN (кабінет → Налаштування → API), VCHASNO_RRO_FN (фіскальний номер каси, GET /api/v1/rro), VCHASNO_DEFERRED_COD, VCHASNO_DEFAULT_POSTAL. Формат звірено з відкритим клієнтом sashalenz/vchasno-kasa-api; офіційна вікі — wiki-kasa.vchasno.ua. Не перевірено на живому акаунті — потрібні ключі.
Змінні Checkbox
CHECKBOX_LICENSE_KEY, CHECKBOX_PIN_CODE (або логін/пароль касира), CHECKBOX_AUTO_SHIFT (відкриває зміну автоматично). Офіційні доки: api.checkbox.ua/api/redoc.