Ссылка скопирована
Мы используем cookie и Яндекс.Метрику, чтобы сайт работал лучше
Axtar

Информация по интеграции

Содержание:

Маркетинговые рассылки — это API МедФлекса, которое позволяет партнёрским сервисам формировать сегменты ваших пациентов по разным условиям — например, «мужчины 35+, не были у стоматолога полгода» — и отправлять им персонализированные сообщения: акции, напоминания о профилактике, поздравления с днём рождения.

Функциональность отличается от привычных триггерных рассылок:

  • Триггерные рассылки — автоматические напоминания на конкретные события: запись, приём, отмена.
  • Маркетинговые рассылки — целевые рекламные кампании по сегментам пациентов: акции, возврат ушедших, профилактика, допродажи.
На данный момент функциональность доступна только клиникам на МИС МедЛок. Подключение остальных МИС запланировано следующим этапом, точные сроки пока не определены.

Как это работает

От клиники требуется только включить интеграцию в личном кабинете МедФлекса, переключатель маркетинговых рассылок в МедЛоке и заключить договор с сервисом. После этого сервис может отправлять запросы в МедФлекс на создание сегментов пациентов по заданным параметрам. Далее необходимо:

  1. Создать сегмент аудитории в интерфейсе сервиса партнёра. Например, «пациенты, отменившие запись за последние 7 дней и не записавшиеся повторно».
  2. МедФлекс собирает сегмент. Мы обращаемся к данным вашей МИС и подбираем пациентов под условия, переданные партнёром по API, попутно применяя ограничения, которые защищают клиентскую базу (подробнее в разделе ниже).
  3. Партнёр получает временные идентификаторы пациентов. Они не содержат никаких персональных данных и действуют 24 часа.
  4. Партнёр запрашивает контакты непосредственно перед отправкой. Мы передаём имя, отчество, телефон, e-mail и возрастную группу — и только на этом этапе. Хранить эти данные партнёру запрещено договором - они используются только в момент отправки сообщения.
  5. Партнёр сообщает нам, кому отправил рассылку. Это нужно, чтобы не отправлять этим пациентам одну и ту же рассылку повторно в ближайшее время.

Какие задачи можно закрыть через маркетинговые рассылки

Ниже — примеры сценариев, которые доступны через рассылки. Список возможных кейсов зависит от технической реализации на стороне сервиса, который вы подключите.

  • Возврат после отмены записи. Пациенту, который отменил визит и не записался снова, можно отправить предложение вернуться.
  • Напоминание о плановой профилактике. Пациентам, которые давно не были на регулярном осмотре, можно отправить напоминание записаться.
  • Поздравление с днём рождения. Именинникам, которые хотя бы раз были в клинике за последний год — персональное поздравление с подарком.
  • Сопровождение после завершения курса лечения. Пациентам, прошедшим курс процедур — рекомендация поддерживающих визитов.
  • Возврат «брошенного» курса лечения. Пациентам, которые начали курс и перестали приходить — напоминание о важности продолжения.
  • Возврат «дорогих» пациентов. Пациентам с высоким суммарным чеком, которые давно не приходили — персональное предложение.
  • VIP-обслуживание. Пациентам с высоким средним чеком — предложения на особых условиях.
  • Разные сообщения для первичных и вторичных пациентов. Первичным — адрес клиники и список документов, вторичным — короткое напоминание.
  • Информирование о новом враче или услуге. Пациентам смежных специальностей, которые ещё не пользовались новой услугой.
  • Реанимация «спящей» базы. Пациентам, которые не были в клинике 1–3 года, — персональные предложения с учётом их истории трат.

Доступные параметры аудитории

По каким параметрам можно сформировать сегмент пациентов в API МедФлекса:

  • Пациент: пол, возрастная группа, дата рождения (диапазон ±7 дней от сегодня), период регистрации в базе МИС (до 5 лет назад)
  • Приём: ЛПУ, период визита (до 3 лет назад), статус приёма, врач, специальность, услуга, количество приёмов по условиям блока
  • Статистика за всё время: количество визитов, сумма покупок, средний чек
  • Исключения: пациенты, которым отправляли определённую рассылку за последние N дней (до 45); пациенты, попавшие в базу при массовом импорте
Важно: Партнёр может предлагать клиникам в своём интерфейсе не все параметры для создания сегмента — это зависит от реализации на его стороне.

Ограничения сегментов

Актуальны на 17.08 (могут быть пересмотрены в будущем):

  • минимум пациентов в сегменте - 1
  • максимум пациентов в сегменте - 5% от общей базы клиники
  • максимум пациентов во всех сегментах за 1 календарный месяц - 30% от общей базы клиники
  • максимум готовых сегментов (можно запросить перс. данные пациентов для рассылки) у партнёра - 10
  • максимум активных сегментов (не архивированы) у партнёра - 100
  • максимум активных сегментов клиники (по всем партнёрам) - 100
  • время "жизни" id пациента - 24 часа

При достижении лимита партнёр получает соответствующую ошибку по API МедФлекса.

Какие пациенты не будут переданы в сегментах (настройки в МедЛоке):

  • Пациент отказался от обработки персональных данных
  • Пациент не дал разрешение на отправку уведомлений (или есть «Отказ от рекламных рассылок»).
  • Приём пациента анонимный
  • У врача, к которому записан пациент, стоит запрет на отправку данных.

Методы API

Доступны по ссылке https://developer.medflex.ru/marketing/

Схема взаимодействия и порядок вызовов

  1. Получите список баз данных — GET /marketing/databases/.
  2. При необходимости получите справочники для условий отбора — врачей, специальности, услуги (GET /models/doctor/, GET /models/speciality/, GET /services/prices/).
  3. Создайте запрос на сегмент — POST /marketing/segments/, в ответ приходит segment_uuid
  4. Опрашивайте статус, пока сегмент не станет ready или failed — GET /marketing/segments/{segment_uuid}/. Callback не предусмотрен - только polling.
  5. Запросите персональные данные под конкретную отправку — POST /marketing/segments/{segment_uuid}/results/.
  6. Зарегистрируйте успешную рассылку — POST /marketing/mailings/.

Список сегментов — GET /marketing/segments/, удаление сегмента — DELETE /marketing/segments/{segment_uuid}/.

Статусы сегмента

pending и in_progress сегмента — разные по смыслу состояния:

  • pending означает, что запрос принят и поставлен в очередь на расчёт
  • in_progress — расчёт уже идёт.

failed может означать как ошибку в самих условиях сегмента, так и временный сбой — по ответу эти два случая различить нельзя. Если сегмент упал в failed, имеет смысл через некоторое время пересоздать тот же запрос ещё раз, а не считать его гарантированно неисправимым.

Время расчёта сегмента сильно зависит от размера базы клиники и количества условий фильтрации: типичное время — около 5 секунд, худшее — до 5 минут. Планируйте поллинг с учётом этого разброса, а не рассчитывайте на мгновенный ответ.

Идентификаторы пациента триггерного и маркетингового API

patient_id и patient uuid - это два разных идентификатора. Сопоставить пациента из маркетингового сегмента с пациентом из приёма по этим полям нельзя.

Идентификатор пациента в Marketing API рандомизирован в целях защиты базы пациентов клиники и для одного и того же пациента живёт только 24 часа.

TTL сегмента и дедлайн на рассылку

Сегмент и его patient_ids живут ровно столько же, сколько живёт идентификатор пациента — 24 часа с момента создания сегмента. Отправить рассылку и зарегистрировать её через POST /marketing/mailings/ нужно обязательно в этот интервал, т. к. по истечении 24 часов POST /marketing/mailings/ вернёт 404.

Если запросить пересчёт сегмента по истечении 24 часов, в нём может оказаться уже другой набор пациентов, чем при первом расчёте.

Идемпотентность и повторные регистрации рассылки

POST /marketing/mailings/ не использует заголовок Idempotency-Key. МедФлекс не ограничивает партнёра в количестве записей о рассылке — можно зарегистрировать несколько записей с одинаковым success_mailing_name.

days_from_mailing в exclude_patients отсчитывается от последней регистрации рассылки с этим именем, а не от первой.

Исключение пациентов (в exclude_patients) по success_mailing_names переживает ротацию patient_id: внутри МедФлекса patient_id привязан к постоянному внутреннему идентификатору пациента в базе МедФлекса.

Какие значения success_mailing_name допустимы

Любое значение в рамках правил валидации самого поля (до 50 символов, только латинские буквы, цифры, дефис и подчёркивание). Фиксированного справочника типов рассылок нет — название придумывает партнёр.

Лимит на выгрузку пациентов

Лимит — 30% уникальных пациентов в календарный месяц.

  • Считается по базе данных (database_id из GET /marketing/databases/) и покрывает все lpu_ids, которые входят в эту базу.
  • Если у одного партнёра несколько баз данных (редкий, но возможный случай) — общего потолка на партнёра нет, у каждой базы свой отдельный счётчик.
  • Сбрасывается 1-го числа каждого календарного месяца в 00:00.
  • 30% считается от размера базы на момент расчёта конкретного сегмента, а не от размера, зафиксированного на начало периода.

Хранение и обработка полученных данных

Правила и сроки хранения данных, полученных через API, определены договором с МедРокет и приложениями к нему — они относятся ко всем данным, полученным через любой метод API (приёмы, услуги, врач, персональные данные пациентов), а не только к конкретному эндпоинту, в описании которого это упомянуто.

Ссылка на договор - https://medflex.ru/static/dms/pdf/contracts/standard-license-contract-service-ru.pdf

Для чего нужна регистрация рассылки

Зарегистрированные через этот вызов пациенты учитываются в exclude_patients.success_mailing_names и исключаются из будущих сегментов с тем же success_mailing_name. Других способов использования этих данных нет.

Тестовое окружение

Отдельная песочница не предусмотрена. Для тестирования МедФлекс предоставляет данные тестовых клиник (не реальных). Хостнейм, URL и остальные параметры те же, что и в проде. Разница только в токене: по тестовому токену доступны исключительно данные тестовых клиник. Этот токен остаётся у партнёра и после завершения разработки — пригодится при тестировании доработок. Для прода выдаётся отдельный токен, по которому будут доступны данные реальных клиник, подключивших интеграцию в личном кабинете МедФлекс.

Токен с доступом к тестовым клиникам передаёт персональный менеджер партнёра.

Базовый URL и версионирование

Используйте базовый URL без версии в пути — https://api.medflex.ru. Постфикс /v1/
устарел и редиректит на тот же URL без него.

О редких изменениях в API менеджер МедФлекса уведомит в чате не менее чем за 2 недели до внедрения.

Лимиты запросов, таймауты и повторные вызовы

Лимит запросов в секунду (RPS) индивидуален для каждого партнёра и зависит от количества подключённых клиник. Формула расчёта зафиксирована в договоре с МедРокет - https://medflex.ru/static/dms/pdf/contracts/standard-license-contract-service-ru.pdf

Дополнительно, на полностью идентичные запросы (тот же метод и то же тело — тот же врач, пациент, слот, филиал, приём и так далее), повторённые в течение 30 секунд после первого, МедФлекс отвечает 429. Запросы с другим телом обрабатываются в обычном режиме — ограничение действует именно на повтор одного и того же запроса, а не на общий поток. При этом отдаётся заголовок Retry-After со значением в секундах (исходное значение — 30).