Документація

Швидкий старт

Швидкий старт нове Архітектура Шлюзи HTTP API Передоплата і правила Фіскалізація Сповіщення і CRM Посилання на оплату Аналітика нове Польща Нативний шлюз Shopify Безпека нове

🆕 Що нового усі релізи →

v0.18.0 2026-11-01 Здоров’я системи, live-перевірка всіх 13 шлюзів, правила комісій, OpenAPI, Docker, E2E розширень великий реліз

🩺 Сторінка «Здоров’я»: процес, БД, диск, бекапи, вебхуки, черги, чеки, по кожному PSP за добу + live-латентність; Telegram /health; сторож пише, коли стає критично і коли відновилось
🧭 Майстер і health перевіряють усі 13 шлюзів живими запитами (monoparts, privatparts, NovaPay, P24, PayU, Tranzzo, RozetkaPay, Portmone додано)
💸 FEE_RULES: ставки комісій за провайдером × країною × валютою × сумою (+ фіксована), розбивка комісій за ринками в аналітиці
📜 OpenAPI 3.1 (/openapi.yaml, 88 маршрутів) + колекція Postman
🐳 Docker: Dockerfile + docker compose з Caddy і бекапами
🧪 E2E-тест Checkout-розширень у Chromium проти локального сервера (64 перевірки); знайдено й виправлено баг вибору міста в NP-pickup
🔧 Вкладки адмінки в два рядки на десктопі

v0.17.1 2026-11-01 Вкладки адмінки

На десктопі вкладки переносяться на другий рядок замість обрізання; на телефоні — прокрутка з підказкою-градієнтом, активна вкладка сама в полі зору

v0.17.0 2026-11-01 Майстер налаштування, інспектор вебхуків, панель безпеки, відновлення з бекапу великий реліз

🧭 Майстер налаштування: живі перевірки Shopify, кожного PSP, Telegram, SMTP, Нової Пошти, CRM, ПРРО і бекапів — з підказкою, який ключ виправити
📥 Інспектор вебхуків: кожен вхідний вебхук із результатом підпису, замовленням, відповіддю, тілом; фільтри і «повторити»
🛡️ Панель безпеки: невдалі входи, заблоковані IP з розблокуванням, активні сесії із завершенням по одній або всіх разом
💾 ops/restore.sh: відновлення з бекапу з перевіркою цілісності; щотижнева перевірка всіх бекапів із тривогою в Telegram
🧩 extension/setup.sh: Partner app з усіма 4 розширеннями однією командою (+ --check)

v0.16.0 2026-11-01 Листи покупцю, щоденна звірка, Shopify Markets, чеки повернення по позиціях великий реліз

✉️ Листи покупцю: «оплату отримано» зі складом замовлення і чеком, окремий лист із чеком ПРРО, лист про повернення (uk/ru/en)
🧮 Щоденна звірка Shopify ↔ Місток ↔ PSP: втрачені вебхуки лікуються самі, розбіжності — у Telegram; кнопка «Звірка» в адмінці
🌍 Shopify Markets: оплата у валюті покупця там, де шлюз її підтримує, інакше в гривні; запис у Shopify у валюті замовлення
🧾 Чеки повернення по реальних позиціях, масштабованих до повернутої суми
Кнопка Apple Pay / Google Pay на Thank-you page; графік розстрочки «від ₴X/міс» під кнопками і в SMS-нагадуванні
📱 Мобільна адмінка, 💾 експорт/імпорт налаштувань, 🧪 «Тестова покупка» одним кліком

v0.15.0 2026-11-01 Промокоди в аналітиці, експорт для бухгалтерії, сторінки оферти й тарифів, мультимагазин великий реліз

🎟️ Промокоди та знижки в аналітиці: замовлення, оплати, конверсія, середній чек і сума знижок по кожному коду; висновки про маржу
📒 XLSX для бухгалтерії за місяць: оплати, повернення, чеки, підсумок по провайдерах з комісіями (кнопка на сторінці Платежі)
📄 Сайт: публічна оферта, політика конфіденційності, тарифи, форма заявки → Telegram + розділ «Заявки» в адмінці
🏪 Кілька магазинів на одному сервері: INSTANCE=shop2 PORT=3001 DOMAIN=… — окремі база, секрети, сервіс, бекапи, домен
💳 Stripe: фактична комісія з balance_transaction

Година на тестовому магазині, ще година — на бойовий токен і домен.

Тестовий токен mono: api.monobank.ua → «Create test token».Бойовий токен — у кабінеті plata by mono після договору еквайрингу.
Shopify → Settings → Payments → Manual payment methods → Create custom → plata by mono.За потреби додайте «Покупка частинами mono», «Оплата частинами ПриватБанк», «Przelewy24», «PayU», «Stripe», «Накладений платіж + передоплата».
Settings → Apps and sales channels → Develop apps → app зі scopes read_orders, write_orders (для посилань на оплату — ще read_draft_orders, write_draft_orders).Скопіюйте Admin API access token і API secret key.
git clone … && cd server && cp .env.example .env — заповніть BASE_URL, SHOPIFY_*, MONO_TOKEN, ADMIN_KEY.
npm i && npm test && npm start або docker compose up -d.Локально: ngrok http 3000 → підставте адресу в BASE_URL. Вебхуки Shopify реєструються автоматично.
shopify app init → «Build an extension-only app».
shopify app generate extension --template checkout_ui --flavor preact --name mistok-thank-you → замініть src/Checkout.jsx і секції targeting/settings у toml нашими з extension/mistok-thank-you.
shopify app generate extension --template customer_account_ui --flavor preact --name mistok-order-status → замініть файлами з extension/mistok-order-status (network_access = true).
shopify app dev → shopify app deploy → встановіть app у магазин.
Settings → Checkout → Customize → Thank you → Add block → у налаштуваннях блоку pay_base_url = ваш BASE_URL, providers = mono,monoparts. Те саме на Order status.
(опція) Вставте extension/email-snippet.liquid у Settings → Notifications → Order confirmation — посилання на оплату буде і в листі.
Тест: замовлення → «plata by mono» → кнопка на Thank-you page → тестова оплата → замовлення Paid, теги mistok-paid, mono:<id>; Order status показує «Оплачено».
Тест: Refund у адмінці → повернення в кабінеті mono. Cancel → рахунок анульовано. Відкрийте /admin/dashboard?key=….
Прод: бойовий токен, TRUST_PROXY=1 за nginx/Cloudflare, HTTPS, FISCAL_MODE, Telegram, SMTP.

Майстер налаштування, одна команда для Partner app, відновлення нове

Адмінка → 🧭 Майстер («Перевірити») — живі перевірки кожного ключа з .env лише читанням: Shopify (магазин, план, валюта, зареєстровані вебхуки), mono (/api/merchant/details), Stripe (баланс), LiqPay / WayForPay / Fondy (запит статусу неіснуючого замовлення — підтверджує ключі без оплати), Telegram (getMe + чат), SMTP (verify), Нова Пошта, CRM, ПРРО, бекапи. До кожної помилки — підказка, який ключ виправити. JSON: GET /admin/api/setup?run=1.
Partner app одною командою: bash extension/setup.sh --store my-store.myshopify.com --base-url https://pay.example.com збирає всі 4 розширення в extension/app/extensions/, ставить залежності, пише SETTINGS.md зі значеннями для редактора checkout/теми й лишає два фінальні кроки: shopify app dev, shopify app deploy. --check лише валідує toml/JSX.
Відновлення з бекапу: bash /opt/mistok/ops/restore.sh (список), … latest --yes (останній), … --verify (перевірка всіх бекапів: gzip + integrity_check; таймер mistok-backup-verify робить це щотижня і при збої пише в Telegram). Перед заміною поточна база зберігається як pre-restore-*.

Docker: cp server/.env.example mistok.env (прибравши коментарі, див. ops/docker.md) → DOMAIN=pay.example.com docker compose up -d — Місток + Caddy (HTTPS) + бекапи кожні 4 год. Образ збирається з кореня репозиторію (Dockerfile).
Специфікація API: /openapi.yaml (OpenAPI 3.1, усі публічні й адмінські маршрути, схеми вебхуків) і /postman_collection.json — для інтеграторів.
E2E-тест розширень: npm run test:e2e рендерить справжні Thank-you / Order status / NP-pickup блоки в Chromium проти локального сервера (64 перевірки, ~15 с) — без dev-магазину.

Усе, що потрібно для бойового режиму, — ваш договір еквайрингу з банком/PSP. Місток не є стороною платежу.