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

Сповіщення, Telegram, CRM

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

Нагадування про неоплачене

Через REMINDER_AFTER_HOURS після створення рахунку, якщо замовлення досі pending: email (SMTP) і, за SMS_REMINDER=true, SMS з тим самим посиланням на оплату. Кількість і інтервал — REMINDER_MAX, REMINDER_GAP_HOURS. Оплатили іншим способом або скасували — нагадування зупиняються.

SMS

SMS_PROVIDER=turbosms|alphasms. SMS_ON_PAID=true — «оплату отримано» покупцю. Телефони нормалізуються до 380XXXXXXXXX.

Telegram-бот

TELEGRAM_BOT_TOKEN + TELEGRAM_ADMIN_IDS. Алерти йдуть у TELEGRAM_CHAT_ID; команди приймаються лише від адмінів.

Команда	Дія
`/today`, `/week`	зведення: замовлення, оплати, виручка, втрачено, по шлюзах, аномалії
`/status #1001`, `/sync #1001`	стан платежу; примусова синхронізація зі шлюзом
`/link 1250 Худі чорне M \| email \| телефон`	чернетка в Shopify + посилання на оплату за 5 секунд
`/refund #1001 300` → `/confirm`	повернення через Shopify (далі Місток відправить його в шлюз)
`/cod_off 380… причина`, `/cod_on`, `/trusted`, `/rules`	правила по телефонах

CRM / Zapier / Make

Підписаний вебхук подій — формат на сторінці API. KeyCRM і SalesDrive приймають його через вхідний webhook/ApiX-Drive; власний бекенд — напряму.

Meta CAPI, GA4, Sendpulse

Після успішної оплати Місток надсилає серверні події — вони не залежать від блокувальників реклами і браузера покупця:

Куди	Що	Змінні
Meta Conversions API	`Purchase` (передоплата — `InitiateCheckout`): сума, валюта, товари, `event_id = mistok-<orderId>` для дедуплікації з піксельною подією; email/телефон/країна/місто хешуються SHA-256, сирі дані не передаються	`META_PIXEL_ID`, `META_CAPI_TOKEN`, `META_TEST_EVENT_CODE`
GA4 Measurement Protocol	`purchase` (передоплата — `begin_checkout`) з `transaction_id`, items, value; `client_id` — стабільний псевдо-id із номера замовлення (cookie `_ga` сервер не бачить)	`GA4_MEASUREMENT_ID`, `GA4_API_SECRET`
Sendpulse	подія Automation360 при оплаті та при кожному нагадуванні про неоплачене (з `pay_url`) — ланцюжки email/Viber/SMS будуєте в Sendpulse; опційно контакт додається в адресну книгу зі змінними	`SENDPULSE_ID`, `SENDPULSE_SECRET`, `SENDPULSE_EVENT_PAID`, `SENDPULSE_EVENT_UNPAID`, `SENDPULSE_BOOK_ID`

Помилки пікселів не впливають на платіж: вони пишуться в таймлайн замовлення (стадія pixels). Якщо у магазині вже є канал Facebook & Instagram від Shopify, він теж шле Purchase зі своїм event_id — щоб не подвоювати, залиште один із двох або перейменуйте нашу подію через META_EVENT_NAME.

KeyCRM — нативний коннектор

Крім універсального вебхука, Місток уміє писати напряму в KeyCRM (OpenAPI, Bearer-ключ з кабінету). Дві схеми:

`KEYCRM_MODE`	Коли підходить	Що робить Місток
`payments` (типово)	замовлення вже прилітають у KeyCRM з Shopify штатною інтеграцією KeyCRM	знаходить замовлення за `source_uuid` (номер замовлення Shopify, напр. `#1001`) і додає оплату `POST /order/{id}/payment`: сума в грн, `status: paid`, метод = назва шлюзу, дата оплати, коментар з id інвойсу
`orders`	штатної синхронізації немає	якщо замовлення не знайдено — створює його (`POST /order`: джерело `KEYCRM_SOURCE_ID`, покупець, товари з SKU і цінами, доставка з адресою), потім додає оплату; з `KEYCRM_PAID_STATUS_ID` переводить у потрібний статус

Передоплата позначається як «Передоплата #1001», повна оплата — «Оплата #1001».
Повернення: часткове — запис оплати зі статусом canceled на суму повернення («Повернення #1001»); коли повернено все — оригінальна оплата переводиться в canceled.
Фіскальний чек — у коментар менеджера замовлення.
Дублікати вебхуків не створюють другу оплату: зв’язок «замовлення Shopify → замовлення і оплата в KeyCRM» зберігається в БД.
Ліміт KeyCRM — 60 запитів/хв на ключ; помилки йдуть алертом власнику, вебхук PSP при цьому не блокується.

Формат звірено з docs.keycrm.app через згенерований клієнт plakidan/key-crm. SalesDrive — наступний у черзі.

SalesDrive — нативний коннектор

`SALESDRIVE_MODE`	Коли підходить	Що робить Місток
`payments` (типово)	замовлення вже синхронізуються штатною інтеграцією SalesDrive ↔ Shopify	додає оплату `POST /api/payment/` з прив’язкою за `orderExternalId` = номер замовлення Shopify, `uniqueId = mistok-<invoice>` (повтори не дублюються); ставить `paymentDate`, `payment_method` і статус `SALESDRIVE_PAID_STATUS_ID`
`orders`	штатної синхронізації немає	створює замовлення через `POST /handler/` (контакт, товари з SKU, спосіб доставки, відділення НП з атрибутів замовлення), потім додає оплату за `orderId`

Повернення — вихідний платіж із від’ємною сумою («Повернення #1001»).
Вибір відділення НП на Thank-you page → shipping_address замовлення в CRM.
Ліміти SalesDrive: /api/order/list/ — 10 запитів/хв; Місток його не використовує в гарячому шляху.

Формат звірено з відкритим клієнтом dannychirkov/salesdrive-api і базою знань SalesDrive; Swagger — api.salesdrive.me/api/docs. Не перевірено на живому акаунті.

Системні події в Telegram

Окрім алертів, бот власника отримує системні події (TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID; вимкнути — SYS_EVENTS=off, мова — SYS_EVENTS_LANG=uk|ru):

🚀 нова версія після деплою — для великих релізів повний список нових функцій, для решти один рядок «оновлено X → Y»;
⚙️ хтось змінив налаштування в адмінці (хто і які ключі), 👥 створив / вимкнув користувача, 🧪 увімкнув чи вимкнув пісочницю;
🚫 5 невдалих входів поспіль — IP заблоковано на 15 хвилин;
🔁 провайдер не відповів і спрацював failover; 💾 пропущений бекап (через systemd OnFailure).

Те саме доступне і в адмінці: 🧾 Журнал дій. Мова адмінки перемикається кнопкою UA | RU у шапці (cookie, окремо для кожного браузера).

Листи покупцю

Коли налаштовано SMTP_* (і EMAIL_ON_PAID не вимкнено), покупець отримує: «Оплату отримано» зі складом замовлення, сумою і посиланням на фіскальний чек (якщо чек ПРРО з’являється пізніше — окремий лист із чеком, коли він готовий), і «Повернення» після refund. Мова — EMAIL_LANG=uk|ru|en. Нагадування про неоплачене замовлення для розстрочки містять графік «N × сума».

Щоденна звірка

О 07:00 (Київ) Місток звіряє три джерела за останні RECONCILE_DAYS (3) дні: Shopify (статус оплати, спосіб), свою базу і виписку PSP. Втрачені вебхуки лікує сам (перечитує статус у PSP і проводить оплату), решту — у Telegram: оплачено тут, але в Shopify не PAID; позначено оплаченим у Shopify вручну без платежу; старі неоплачені; hold понад 5 днів. Вручну: кнопка в адмінці або POST /admin/reconcile/run. Вимкнути: RECONCILE=off, час — RECONCILE_HOUR.

Shopify Markets (валюти)

Якщо покупець бачить ціну в злотих або євро, а магазин веде облік у гривні, Місток обирає валюту списання сам: PLN/EUR-здатний шлюз (P24, PayU, Stripe, Fondy) отримує суму у валюті покупця, гривневий (mono, LiqPay…) — суму в гривні, яку Shopify уже перерахував; у Shopify оплата записується у валюті замовлення. Чеки повернення формуються по реальних позиціях, пропорційно масштабованих до повернутої суми (знижки, часткові повернення) — без анонімного рядка «Повернення».

Алерти

Slack/Discord/Mattermost (ALERT_WEBHOOK_URL) і Telegram: розбіжність суми, reversed, невдале повернення, збій шлюзу з failover, шторм поганих підписів, ризиковий накладений платіж, помилка ПРРО.