Печатные формы, 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 — без неё подписка будет выглядеть созданной и активной, но не получит ни одного события.