Мария Зайцева
Клиника за полгода подключила трёх разных внешних партнёров: агрегатор онлайн-записи, страховую компанию для сверки полисов ОМС и курьерскую службу доставки анализов на дом. Каждое подключение разработчики делали отдельной доработкой: свой кусок кода, свои костыли под формат конкретного партнёра, своя переписка о том, что именно можно отдавать. На третьей интеграции стало очевидно — так проект не масштабируется, потому что API задуман «под одного партнёра», а не как продукт. Чтобы не повторять этот путь с нуля на каждом следующем подключении, стоит сразу спроектировать API клиники, которое безопасно подключают внешние партнёры, а не дорабатывать точечно под каждого.
Зачем клинике открытое API, если есть МИС
Интеграция с МИС и открытие API внешним партнёрам — разные по риску задачи. МИС — это система, которой клиника управляет сама и которой доверяет как своей. Внешний партнёр — не твоя система: агрегатору записи, страховой или курьерской службе нельзя доверять так же, как внутреннему модулю, даже если договор подписан и партнёр добросовестный. Поэтому для партнёров нужен отдельный контракт доступа — чётко описанный API, а не проброс внутренних интерфейсов МИС наружу.
Кто обычно просит доступ к данным клиники: агрегаторы онлайн-записи, которым нужна информация о свободных слотах и услугах; страховые компании ОМС и ДМС — для сверки полисов и статуса прикрепления пациента; сервисы доставки анализов на дом — для передачи заказа и статуса выполнения; SMS- и push-провайдеры напоминаний о визите; иногда — бухгалтерские и ERP-системы для сверки платежей. У каждого из них разная задача и разный набор данных, который им реально нужен.
Что можно отдавать наружу, а что нельзя никогда
Партнёрам можно открывать доступность слотов записи, перечень услуг и цены, статус записи или посещения — то есть сам факт «пациент записан» или «пациент был на приёме» без привязки к содержанию визита.
Нельзя отдавать без отдельного юридического основания и явного согласия пациента: диагнозы, результаты анализов, назначения и любые другие сведения, которые относятся к специальным категориям персональных данных по 152-ФЗ. Это касается даже технически надёжных партнёров — правило не про доверие к конкретной компании, а про то, что такие данные вообще не должны покидать периметр МИС без отдельного правового основания.
Из этого следует практическое правило: партнёрское API — это отдельный, более узкий слой поверх МИС, а не прямой проброс внутренних данных наружу. Слой сам решает, что отдать конкретному партнёру, МИС про существование внешних партнёров может вообще не знать.
Права доступа — scope, а не общий ключ на всё
Частый антипаттерн на старте — один API-ключ с полным доступом, который выдают всем партнёрам подряд, потому что «так быстрее». Проблема вскрывается не сразу: если ключ утечёт у одного партнёра или партнёр начнёт запрашивать данные, которые ему не положены, остановить это без отключения всех остальных интеграций сразу невозможно.
Правильный паттерн — доступ через OAuth2 client credentials или аналогичную схему с отдельными scope на каждого партнёра: например, slots:read для доступности записи, booking:write для создания брони, policy:verify для сверки полиса. У страховой компании при такой схеме просто нет технической возможности запросить данные о записи, а у агрегатора — данные о полисах, даже если кто-то ошибётся в настройке на стороне партнёра.
Отдельное обязательное условие — лог обращений по каждому партнёру: кто, когда и что именно запросил. Без такого журнала разбор инцидента («кто получил доступ к данным пациента и когда») превращается в гадание, а при проверке регулятора — в проблему уже для самой клиники.
Webhook или polling — когда что
Для событий — запись создана, перенесена или отменена — удобнее webhook: клиника сама уведомляет партнёра в момент события, нагрузка на API ниже, чем при постоянных опросах. Обратная сторона — нужна ретрай-логика на стороне клиники: если эндпоинт партнёра временно недоступен, уведомление нельзя просто терять, его нужно повторять по расписанию.
Для данных, которые партнёр тянет сам по расписанию — например, справочник услуг и цен, — проще и надёжнее polling: партнёр сам запрашивает актуальное состояние раз в заданный интервал. Реализация проще, чем у webhook с ретраями, но есть неизбежная задержка обновления данных на стороне партнёра.
Версионирование — почему нельзя менять API «по живому»
Партнёры интегрируются с API клиники один раз и годами не трогают код на своей стороне — ровно до тех пор, пока что-то не сломается. Breaking change без версии — изменение формата ответа, переименование поля, смена логики авторизации — ломает сразу всех подключённых партнёров одновременно, а не одного.
Рабочая практика — явная версия в URL (например, /api/v2/slots) или в заголовке запроса, и обязательная поддержка предыдущей версии в течение нескольких месяцев после анонса новой. Партнёр должен успеть перейти на новую версию в своём темпе, а не аварийно чинить интеграцию в день релиза.
Документация и песочница — то, без чего партнёр не подключится сам
Без открытой OpenAPI/Swagger-спецификации, тестового stage-контура с фиктивными данными пациентов и отдельных тестовых ключей каждое новое подключение превращается в переписку разработчиков партнёра с разработчиками клиники — медленно и не масштабируется на пятого, десятого партнёра.
Песочница с тестовыми данными даёт партнёру возможность проверить интеграцию до того, как она коснётся реальных пациентов, а документация снимает большую часть вопросов ещё до первого обращения в поддержку.
Часто задаваемые вопросы
Можно ли дать агрегатору доступ напрямую к МИС?
Нет, прямой доступ внешнего партнёра к МИС — это риск: МИС хранит медицинские данные, к которым у агрегатора записи не должно быть доступа вообще. Правильная схема — отдельный API-слой со своими scope, который отдаёт наружу только то, что разрешено конкретному партнёру.
Нужно ли уведомлять пациента, что его данные о записи видит внешний агрегатор?
Да, это отражается в политике обработки персональных данных клиники. Пациент должен понимать, что информация о записи (но не диагноз и не результаты анализов) может передаваться партнёру, через которого он записался.
Сколько стоит спроектировать такое API с нуля?
Зависит от числа партнёров и типов интеграций: API с одним scope для одного агрегатора и API, рассчитанное сразу на страховые, курьерские службы и SMS-провайдеров, — разные по трудоёмкости задачи. Точную оценку даёт команда, которая проектирует такие интеграции под ключ.
Что делать, если партнёр перестал платить или ушёл?
Scope и ключ этого партнёра должны отключаться независимо от остальных интеграций — без правок общего кода API и без влияния на других подключённых партнёров. Это одна из причин, почему доступ изначально проектируют по отдельным scope, а не одним общим ключом.
Открытое API клиники окупается не на первой интеграции, а примерно с третьего партнёра: именно тогда затраты на архитектуру — scope, версионирование, документацию — перестают быть «лишней работой» и начинают экономить месяцы на каждом новом подключении.
