Друковані форми, push-сповіщення і вебхуки

Клієнтка просить «якийсь папірець на процедуру». Майстриня між клієнтами в CRM не дивиться і про перенесення дізнається останньою. Студія веде облік у своїй системі й хоче, щоб оплачені візити падали туди самі. Три різні запити, три різні механізми — і в кожного своя межа, яку краще знати заздалегідь.

Де це в CRM

• Друковані форми: «Налаштування → Процеси → PDF-шаблони».
• Сповіщення на телефон: «Налаштування → Салон → Сповіщення».
• Вебхуки: «Налаштування → Інтеграції → Вебхуки». Пункт видно лише компаніям, у тарифі яких є доступ до API.

Друковані форми: шаблон, змінні, попередній перегляд

Шаблон — це HTML плюс необов'язковий CSS плюс параметри сторінки: формат (A4, A5, Letter), орієнтація і поля в міліметрах. У редакторі три вкладки — HTML, CSS і «Налаштування». Новий шаблон відкривається із заготовкою: шапка з назвою й адресою салону, таблиця з датою, клієнтом, телефоном, майстром і статусом, таблиця послуг і підсумок.

Дані підставляються змінними у фігурних дужках. Їх набір фіксований: компанія ({{company.name}}, адреса, телефон, сайт, логотип), запис ({{appointment.id}}, дата, час початку й кінця, статус, коментар, вартість, відмітка «Оплачено», ПІБ спеціаліста), клієнт (ім'я, телефон, пошта, адреса), а також {{currency}}, {{document_date}} і дві готові таблиці — {{services_table}} і {{products_table}}. Той самий список віддає довідник API, тож нічого вгадувати не треба.

Шаблонів може бути скільки завгодно, але дефолтний — один на компанію, і неактивний шаблон дефолтним зробити не дадуть. Кнопка «Превью» відкриває готовий PDF із тестовими даними — саме на ньому й перевіряють верстку.

Тепер про межу, і вона суттєва. Кнопки «надрукувати документ для цього візиту» в інтерфейсі немає. Сформувати PDF за реальним записом уміє тільки API — GET /v1/appointments/pdf-templates/{id}/preview/{appointmentId} віддає файл. Тобто зараз розділ — це редактор бланків, а не друк документів із картки клієнта.

Push: пристрої, час тиші, журнал

Це особисті налаштування, і права на налаштування салону вони не вимагають: людина підключає свій телефон, а не чужий. Кнопка «Увімкнути» підписує саме той пристрій, з якого ви її натиснули. Якщо браузер сповіщення заборонив, сторінка так і скаже; на iPhone вони працюють лише в застосунку, доданому на екран «Додому», — про це теж є окрема підказка.

Налаштувань три: слати чи не слати; «На всі пристрої» або «Лише на телефони» (за комп'ютером сповіщення й так видно в інтерфейсі); «Не турбувати з… до…», причому інтервал через північ — звичайний випадок, а не помилка вводу.

Кнопка «Перевірити» шле собі тестове сповіщення і повертає не «успіх», а число пристроїв, які його прийняли. Нуль — це і є відповідь на питання «чому не приходить». Нижче лежить журнал останніх надсилань із причиною, чому не пішло: сповіщення вимкнено, тип вимкнено, час тиші, немає підключених пристроїв, відсіяно налаштуванням «лише на телефони», надсилання не налаштоване. Список пристроїв показує, коли кожен востаннє отримував сповіщення й чому був відключений; сам токен назовні не віддається, лише останні вісім символів — щоб відрізнити пристрій у підтримці.

Push отримує те саме, що й дзвіночок у CRM: нову онлайн-запис, задачі, чати, події каси й складу, розрахунок зарплати. Правило одне — push ніколи не ламає того, через що виник: помилка надсилання гаситься і потрапляє в журнал, а не в екран адміністратора. Сповіщення, адресоване всій компанії, на телефони не йде взагалі: будити вночі тих, кого подія не стосується, гірше, ніж промовчати.

Дві межі. Вимкнути окремі типи сповіщень можна лише через API — перемикачів типів на екрані немає, хоча журнал таку причину відображає. І вся підсистема мовчить, якщо в оточенні не налаштований Firebase: тоді розділ прямо пише, що push тут не налаштовані, замість того щоб показувати кнопку, яка нічого не робить.

Вебхуки: події, підпис, повтори

Підписка — це назва, URL приймача і набір подій; клік по категорії обирає всю категорію одразу. Список подій великий: ліди, клієнти, записи, співробітники, товари, оплати, чати, рахунки, форми, задачі. Реально відправляються ті, під якими є слухач, — записи (створено, оновлено, скасовано, завершено, нагадування), клієнти, ліди, співробітники, товари, задачі.

Тіло події однакове для всіх: event, subscription_id, timestamp і data. Заголовки — X-Beesection-Event, X-Beesection-Delivery-Id і X-Beesection-Signature виду sha256=…, тобто HMAC-SHA256 від тіла запиту. Свої заголовки додати можна, системні перевизначити — ні. Адреса перед кожним надсиланням перевіряється на «внутрішність»: вебхук на внутрішній чи приватний адрес не піде, навіть якщо ім'я вказувало на публічний у момент збереження.

Доставка йде через чергу, а не з обробника запиту: повільний приймач не має гальмувати збереження запису. Таймаут задається від 5 до 120 секунд (за замовчуванням 30), кількість повторів — від 0 до 10 (за замовчуванням 3), паузи ростуть: хвилина, п'ять хвилин, чверть години, година, дві. Кожна спроба лягає в журнал доставок — подія, статус, номер спроби, помилка; у списку підписок поруч стоїть рахунок успіхів і помилок.

Головне обмеження тут одне, і воно ламає очікування: події йдуть лише на верифіковані підписки, а кнопки верифікації в інтерфейсі немає. Верифікація — окремий виклик API (POST /v1/event-subscriptions/{id}/verify): ми надсилаємо на ваш URL {"type":"url_verification","challenge":"…"} і чекаємо у відповіді те саме значення. До цього моменту «Тестовий пінг» теж відмовить. Друге: секрет підписки генерується при створенні, але ніде не показується — ні на екрані, ні у відповіді API, тому перевірити підпис на своєму боці зараз можна, лише діставши секрет із бази.

Є й другий, окремий механізм вебхуків — для партнерського Connect API. Він налаштовується тільки через той самий API, підписує тіло інакше (X-Webhook-Signature рахується від «мітка часу + тіло») і має власні повтори: три спроби з паузами 60, 300 і 900 секунд. Ідентифікатор події там однаковий у всіх спробах — за ним підписник відкидає дублі.

Що варто робити

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

Push увімкніть собі й попросіть увімкнути майстрів — але спершу натисніть «Перевірити». Якщо там нуль, далі йти немає сенсу: журнал одразу назве причину.

Вебхук заводьте лише тоді, коли на тому боці справді є кому приймати запити, і одразу плануйте верифікацію через API — без неї підписка виглядатиме створеною й активною, але не отримає жодної події.