Разделы
На этой странице

Как подключить API заявок и контрактов?

API передаёт внешней системе, например 1С, актуальные заявки, контракты, платежи и доступные чеки одной клиники. Все методы предназначены только для чтения. API не закрывает контракты, не проводит платежи и не формирует чеки.

Включение и ключ

Сначала системный администратор в /admin открывает редактирование клиники, на вкладке Система включает API доступен клинике и сохраняет изменения. По умолчанию это разрешение выключено. Без него раздел API скрыт в кабинете клиники, управление ключом и запросы API недоступны.

После этого главный администратор клиники открывает Настройки → Общие настройки → API для внешних систем, включает доступ и нажимает Сохранить настройки API. Здесь же можно показать, скопировать и перевыпустить ключ. Обычные администраторы не могут управлять ключом. Клиника не может самостоятельно выдать себе системное разрешение.

Отключение разрешения в /admin сразу скрывает раздел и блокирует запросы по существующему ключу. Ключ и настройка включения обмена сохраняются: после возврата разрешения действует прежнее состояние. Для работы API нужны оба условия — разрешение системы и включение обмена клиникой.

Настройки API с включением доступа и управлением единым ключом

У клиники один ключ для обоих ресурсов. Он передаётся в заголовке Authorization: Bearer <API_KEY>. Выключение немедленно блокирует доступ, сохраняя ключ. Перевыпуск немедленно отменяет старый ключ.

Ключ определяет клинику. Параметр clinic_id не поддерживается. Запрос записи другой клиники возвращает 404, как запрос отсутствующей записи.

Методы и формат

Базовый адрес: https://medsenger.ru/api/integrations/v1.

Метод Назначение
GET /consulting-orders Список заявок и получение обновлений
GET /consulting-orders/{id} Одна текущая заявка
GET /contracts Список контрактов и получение обновлений
GET /contracts/{id} Один текущий контракт

Для этих же путей поддерживается HEAD: статус и заголовки без тела ответа. Авторизация, фильтры списков, подготовка выгрузки и лимит запросов действуют так же, как для GET.

Скачать спецификацию OpenAPI 3.0. В ней есть схемы, описания полей, статусы и именованные примеры успешных ответов и ошибок.

Ответы GET имеют Content-Type: application/json и Cache-Control: no-store, private. Список содержит data: [] и meta; отдельная запись — data: {} без meta.

Все даты, включая вложенные платежи и чеки, передаются целым числом секунд Unix timestamp (integer, int64). Например, 1791972000 — 14 октября 2026 года, 10:00 UTC / 13:00 по Москве. Это один момент времени независимо от часового пояса клиента. Датовые фильтры тоже принимают секунды, без строк дат и миллисекунд.

Суммы передаются целым числом копеек: amount_minor: 150000 означает 1500,00 ₽. Валюта — RUB. Фискальные номера и подписи передаются строками: не преобразуйте их в числа, чтобы сохранить все цифры и ведущие нули.

В обычной записи присутствуют все описанные поля, даже если значение неизвестно и равно null. Пустой массив [] означает отсутствие элементов. Отметка об удалении имеет отдельный сокращённый формат. Числовые ID вложенных объектов относятся к соответствующим сущностям Медсенджера; external_id относится к провайдеру.

Параметры списков

Параметры передаются в query string и необязательны. Они поддерживаются у списков; запрос записи по ID не предоставляет фильтрацию.

Параметр Тип Описание
page integer, int64 Номер страницы от 1. По умолчанию 1; верхняя граница текущей реализации — 18446744073709551. Предварительный запрос первой страницы не обязателен.
limit integer От 1 до 500, по умолчанию 100.
updated_since integer, int64 Изменения, опубликованные начиная с указанной секунды, включительно. Без него ограничение по времени изменения отсутствует.
created_from integer, int64 Время создания от указанной секунды, включительно.
created_to integer, int64 Время создания до указанной секунды, включительно. created_from не должен быть позже created_to.
status string Один текущий статус ресурса. Для заявок: created, payment_required, accepted, declined. Для контрактов: waiting_activation, active, expired, closed.
is_paid 0 или 1 Только для заявок с существующим платежом: 0 — неоплаченный, 1 — подтверждённая оплата. Строки true и false не принимаются.

Временные параметры принимают целое число от 0 до 253402300799 (последняя секунда 9999 года). Границы относятся к точным секундам без округления до дней. Условия всех переданных фильтров применяются одновременно через «И».

Списки отклоняют неизвестные параметры с 422 invalid_parameters: например, clinic_id, cursor, sync_token или is_paid для /contracts. Неизвестные параметры не игнорируются. Нельзя передавать revision вместо updated_since.

Ограничения фильтров

status и is_paid выбирают текущее состояние. Например, после оплаты заявка перестанет входить в is_paid=0; отдельного сообщения о выходе из выборки не будет. Заявки без платежа не входят ни в is_paid=0, ни в is_paid=1. Возврат может требовать сверки при сохранённом is_paid=true, поэтому этот фильтр не заменяет проверку payment.status и payment.issue.

Опубликованные отметки об удалении не сохраняют статус, признак оплаты и дату создания. Поэтому любой фильтр status, is_paid, created_from или created_to исключает такие отметки. Даже created_from=0 не вернёт удаления. Один updated_since сохраняет отметки об удалении в выборке.

Для полной синхронизации используйте только updated_since, page и limit. Фильтры для отчётов применяйте к локальной копии. Если нужна ограниченная отчётная выборка с сервера, учитывайте, что по ней нельзя отслеживать все удаления и изменения состава.

Пример отчётного запроса: принятые заявки с подтверждённой оплатой, созданные 14 октября 2026 года по UTC. Это не запрос полной синхронизации:

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'status=accepted' \
  --data-urlencode 'is_paid=1' \
  --data-urlencode 'created_from=1791936000' \
  --data-urlencode 'created_to=1792022399' \
  --data-urlencode 'limit=100'

Формат списка и общие поля

Списки упорядочены по возрастанию id, а не по revision или updated_at. meta не содержит общего количества записей, количества страниц или токена продолжения.

Поле Тип Описание
meta.has_more boolean Есть ли ещё записи, соответствующие запросу. При true запросите page + 1 с теми же фильтрами и размером страницы.
meta.page integer, int64 Номер запрошенной страницы.
meta.limit integer Размер страницы. На последней странице элементов может быть меньше.
meta.generated_at integer, int64 Время начала текущего запроса на сервере. Для следующего цикла синхронизации сохраняйте значение первой успешно полученной страницы текущего цикла.

Пустая страница — успешный ответ 200:

{
  "data": [],
  "meta": {
    "has_more": false,
    "page": 1,
    "limit": 100,
    "generated_at": 1792577160
  }
}

Общие поля обычных заявок и контрактов:

Поле Тип Описание
id integer, int64 Внутренний ID заявки или контракта. Используйте вместе с названием ресурса и clinic_id: ID разных ресурсов могут совпадать.
clinic_id integer, int64 ID клиники, определённой ключом. Не является параметром выбора клиники в запросе.
created_at integer, int64 или null Время создания записи; null, если неизвестно.
revision integer, int64 Номер последнего опубликованного изменения. Счётчик общий для обоих ресурсов одной клиники, поэтому пропуски нормальны. Не является параметром запроса или номером страницы.
updated_at integer, int64 или null Время публикации последнего изменения экспортируемых данных, включая вложенные платежи и чеки. Может отличаться от времени сохранения самой заявки или контракта; null, если неизвестно.

API отдаёт текущее состояние и номер последнего опубликованного изменения. История промежуточных состояний не выдаётся. Страницы независимы и не образуют снимок базы на один момент. Изменения, произошедшие во время обхода, могут появиться в текущем или следующем цикле опроса.

Данные заявки

Поля id, clinic_id, created_at, revision и updated_at описаны выше. Остальные поля:

Поле Тип Описание
status string Статус обработки заявки; значения приведены ниже. Отдельное поле payment.status описывает платёж.
reviewed_at integer, int64 или null Зафиксированное время рассмотрения, принятия или отклонения; null до рассмотрения или при отсутствии данных.
service object Условия услуги на момент оформления; структура описана в разделе «Услуга».
duration_days integer, int64 или null Текущая длительность из заявки в днях; null, если неизвестна. service.duration_days хранит первоначальные условия и не пересчитывается после правок.
doctor object или null Выбранный врач в формате {id, name} либо null, если отсутствует или недоступен.
customer object Сохранённые в заявке контакты заказчика: name, email, phone. Каждое поле — string или null. Они могут отличаться от текущего профиля пациента.
payment object или null Связанный платёж либо null. Отсутствие платежа не подтверждает бесплатность услуги.
contract_id integer, int64 или null ID связанного контракта либо null. Может быть null после оплаты, пока контракт создаётся.
contract object или null Краткое текущее состояние контракта либо null. Содержит только поля из раздела «Состояние контракта»; полного пациента, услуги, врачей, платежей и revision здесь нет.
Статус заявки Значение
created Заявка создана.
payment_required Заявка находится на этапе оплаты. Фактическую оплату проверяйте по платежу: создание контракта может запаздывать.
accepted Заявка принята и связана с контрактом.
declined Заявка отклонена.

Услуга

Блок service одинаков по форме у заявки и контракта. У контракта, созданного по заявке с сохранёнными условиями, эти условия наследуются.

Поле Тип Описание
captured boolean Есть ли сохранённые условия оформления. Для старых записей без снимка — false. Даже true не гарантирует, что известны все значения.
service_id integer, int64 или null ID услуги справочника либо null, в том числе при оформлении без услуги справочника.
name string или null Первоначальное название услуги либо null.
duration_days integer, int64 или null Длительность из сохранённых условий в днях либо null. Не является вычисленной текущей длительностью контракта.
amount_minor integer, int64 или null Известная первоначальная стоимость в копейках либо null. Авторитетная сумма выставленного счёта находится в payment.amount_minor.
currency string Валюта стоимости: RUB.

Последующие изменения справочника не заменяют сохранённые условия. Для старой заявки без снимка сохраняется известная длительность, но неизвестные название и цена остаются null; стоимость не восстанавливается по текущему справочнику.

Врач и контакты

В doctor, main_doctor и responsible_doctor объект врача содержит id (integer, int64 — ID врача клиники, а не ID пользовательского аккаунта) и name (string или null — текущее имя). Сам объект может быть null.

Для customer.name, customer.email и customer.phone используются данные заявки. Для patient.name, patient.email и patient.phone — текущий профиль пациента. Формат телефона не гарантирует нормализацию; неизвестные контакты передаются как null.

Данные контракта

Контракты выгружаются независимо от заявки и онлайн-оплаты. Помимо общих полей и состояния из следующего раздела, ответ содержит:

Поле Тип Описание
number string или null Отображаемый номер контракта либо null. Для сопоставления используйте стабильный id.
consulting_order_id integer, int64 или null ID связанной заявки либо null. Если на контракт ссылается несколько заявок, возвращается наименьший ID.
patient object или null {id, name, email, phone} либо null. id — integer, int64, ID пациента клиники, а не ID пользовательского аккаунта; контакты — string или null.
service object Первоначальные условия услуги, описанные выше.
main_doctor object или null Основной врач в формате {id, name} либо null.
responsible_doctor object или null Текущий ответственный врач. При отсутствии назначенного ответственного подставляется основной врач; при недоступности — null.
contract_type object или null Тип/классификатор контракта: id (integer, int64) и name (string или null). Сам объект — null при отсутствии доступного типа.
is_eternal boolean Текущее значение настройки бесконечных контрактов клиники. Это не отдельный сохранённый флаг контракта; оно не заменяет status и не гарантирует ends_at=null.
payments array Массив связанных платежей клиники по возрастанию их ID, включая неоплаченные. Может быть пустым.

Состояние контракта

Эти поля есть в полном контракте и во вложенном order.contract:

Поле Тип Описание
id integer, int64 ID контракта. Во вложенной структуре равен order.contract_id.
status string Текущее вычисляемое состояние; правила приведены ниже.
starts_at integer, int64 или null Время начала контракта либо null.
ends_at integer, int64 или null Время окончания либо null.
activated_at integer, int64 или null Время активации либо null, если активации ещё не было или дата неизвестна.
is_delayed boolean Настроена ли отложенная активация. Может оставаться true после активации; проверяйте также status и activated_at.
awaiting_conclusion boolean Ожидается ли завершение заключения врача.
concluded_at integer, int64 или null Время завершения работы над заключением либо null.
service_completed_at integer, int64 или null Время явно подтверждённого оказания услуги либо null, если подтверждения нет.
service_completed_by object или null Кто подтвердил услугу: {type, id}, либо null при отсутствии подтверждения. type — doctor, administrator или null; id — integer, int64 или null, ID учётной записи: для doctor — users.id, для administrator — registrators.id. ID учётной записи врача может отличаться от doctor.id врача клиники. Для старых данных отдельные сведения об авторе могут быть неизвестны.

Все даты в таблице — Unix timestamp в секундах.

Статус контракта Условие
closed Контракт закрыт вручную. Имеет наивысший приоритет.
waiting_activation Контракт отложенный и ещё не активирован; проверяется после ручного закрытия.
expired Дата окончания прошла; проверяется после двух условий выше.
active Остальные случаи по текущему алгоритму.

Истёкший или закрытый контракт сам по себе не означает подтверждённое оказание услуги. Ожидание заключения передаётся отдельно. service_completed_at не выводится из наличия итогового чека и доступен без кассы. Повторное открытие не отменяет ранее подтверждённую услугу автоматически.

Изменение срока, врача, активация, завершение заключения и подтверждение услуги попадают в обновления. Истечение срока учитывается без ручного сохранения.

Диагнозы, переписка, медицинские документы, текст заключения, пароли шлюзов и ссылки с токенами входа не передаются.

Платежи

Структура одинакова в order.payment и каждом элементе contract.payments. Один платёж имеет одинаковый ID в обоих ресурсах: при учёте не суммируйте его дважды.

Поле Тип Описание
id integer, int64 Внутренний ID платежа/счёта.
amount_minor integer, int64 Сумма счёта в копейках. Например, 150000 — 1500,00 ₽; может отличаться от сохранённой цены услуги.
currency string Валюта счёта: RUB.
provider string Код платёжного шлюза. Сейчас используются robokassa, yookassa, sberpay; набор может расширяться.
environment string или null Среда платёжного шлюза: test, production или null, если неизвестна. null не означает production.
is_paid boolean Подтверждена ли оплата. После возврата/отмены может сохраняться true; проверяйте status и issue.
paid_at integer, int64 или null Время подтверждения оплаты в Медсенджере либо null. У исторического оплаченного счёта дата может быть неизвестна.
status string Сводное состояние платежа; значения и приоритет приведены ниже.
issue string или null Код причины сверки либо null. Известные коды приведены ниже; набор открытый.
fulfillment_status string или null Состояние действий после оплаты: pending — ожидают выполнения/повтора; done — выполнены; null — не начаты или неизвестны.
external_id string или null Идентификатор платежа у шлюза либо null. Отличается от внутреннего id и идентификатора чека у кассы.
fiscalization object Сохранённые условия облачной фискализации и известные чеки этой покупки.

Статусы платежа

payment.status Значение
not_started Нет сохранённой попытки регистрации платежа.
registering Идёт регистрация платежа у шлюза или уточнение её результата.
pending Ожидается результат попытки оплаты.
paid Оплата подтверждена.
canceled Последняя попытка отменена.
refunded Последняя попытка содержит состояние возврата. В штатной обработке возврат обычно переводит сводный статус в requires_review.
requires_review Есть причина для сверки в issue.

Алгоритм выбирает requires_review при непустом issue; затем paid при is_paid=true; иначе — статус последней попытки по ID, а при отсутствии попытки — not_started. Статусы заявки, платежа, контракта и чека относятся к разным процессам.

fulfillment_status=done означает завершение действий после оплаты, например создания контракта или уведомления агента. Подтверждение оказания самой услуги находится в contract.service_completed_at. Возможна комбинация is_paid=true, fulfillment_status=pending, contract_id=null.

Причины сверки

payment.issue Значение
amount_or_currency_mismatch Сумма или валюта у шлюза не совпала с ожидаемой.
invoice_amount_changed Оплаченная сумма отличается от текущей суммы счёта.
duplicate_payment Обнаружено ещё одно подтверждение оплаты.
refund_requires_review Шлюз сообщил о возврате.
payment_reversed Платёж отменён после подтверждения.
registration_requires_review Регистрация требует сверки; автоматическое повторное выставление остановлено.

issue=null означает отсутствие записанной причины сверки. Незнакомый непустой код тоже требует сверки: не считайте такой платёж обычной успешной оплатой. Например, возврат может выглядеть как is_paid=true, status=requires_review, issue=refund_requires_review; полный ответ есть в OpenAPI, пример ReviewRequiredOrder.

Фискализация и чеки

payment.fiscalization описывает облачную кассу Медсенджера для конкретной покупки. Исторические настройки сохраняются при изменении текущих настроек клиники.

Поле Тип Описание
enabled_for_order boolean Есть ли сохранённые настройки облачной фискализации для покупки. false не является ошибкой и не исключает чеков у шлюза или других систем.
mode string или null on_contract — чек полного расчёта при подтверждённой оплате и связанном контракте; advance — аванс после оплаты и итоговый чек после явного подтверждения услуги и подтверждения авансового чека; null — неизвестно или механизм отключён.
provider string или null Код провайдера кассы; сейчас ofd_ferma (OFD.ru — Ferma). Возможны новые значения. null — неизвестно или механизм отключён.
environment string или null Среда кассы: test, production или null. Указана отдельно от среды платежа; неизвестную среду нельзя считать боевой.
receipts array Известные чеки по возрастанию внутреннего ID. Пустой массив допустим и при включённой фискализации, пока не наступил нужный этап.

В режиме advance итоговый чек планируется после подтверждения авансового чека (status=confirmed) и явного подтверждения услуги. Для дополнительного счёта может требоваться отдельное подтверждение оказания услуги по этому счёту в кабинете: закрытие всего контракта не заменяет его автоматически. При нулевой сумме или наличии причины сверки платежа новые чеки не планируются.

В OpenAPI есть дополнительные полные ответы FullReceiptOrder (режим on_contract) и FiscalizationRetryOrder (временная ошибка связи при status=submitting). В последнем случае поля ссылки и реквизитов ещё неизвестны, а error_code=transport_error не означает окончательный отказ.

Поля чека

Каждый элемент fiscalization.receipts содержит:

Поле Тип Описание
id integer, int64 Внутренний ID чека Медсенджера.
kind string Вид: full — полный расчёт; advance — аванс; settlement — итоговый расчёт по ранее внесённому авансу.
status string Статус обработки чека; значения приведены ниже.
external_id string или null ID чека у провайдера кассы либо null. Не совпадает по смыслу с ID платежа у шлюза или номером фискального документа.
receipt_url string или null Известная HTTPS-ссылка просмотра чека либо null. Может появиться позже первичной отправки.
error_code string или null Последний код ошибки фискализации либо null. Ошибка может быть временной и не обязательно означает status=failed.
fiscal_document object Объект известных фискальных реквизитов. Передаётся всегда, неизвестные значения внутри равны null.

Поля внутри fiscal_document:

Поле Тип Описание
fiscal_drive_number string или null Номер фискального накопителя (ФН). Строка либо null.
document_number string или null Номер фискального документа (ФД). Строка либо null.
fiscal_sign string или null Фискальный признак документа (ФПД). Строка либо null.
registered_at integer, int64 или null Время регистрации чека, Unix timestamp в секундах, либо null при отсутствующей/некорректной дате. Часовой пояс провайдера уже учтён; исторические даты Ferma без смещения трактуются как московские.

Статусы чека

receipt.status Значение
pending Ожидает отправки.
submitting Отправка начата; результат ещё устанавливается.
accepted Провайдер принял запрос.
processed Чек сформирован, ожидается передача в ОФД.
confirmed Передача в ОФД подтверждена.
failed Зафиксирована окончательная ошибка.

При опросе промежуточные статусы могут быть пропущены. Отсутствие ссылки или реквизитов на раннем этапе само по себе не означает ошибку.

error_code — открытый набор диагностических кодов. Примеры: transport_error — ошибка связи; provider_unavailable — провайдер недоступен; authentication_failed — ошибка авторизации кассы; invalid_provider_response — некорректный ответ; payment_requires_review — новые операции остановлены до сверки платежа; ferma_kkt_error — ошибка ККТ; ferma_<число> — код ошибки Ferma. Незнакомый код сохраняйте для диагностики, состояние чека определяйте по status.

Синхронизация

Для полной локальной копии опрашивайте consulting-orders и contracts независимо, с отдельной сохранённой временной границей для каждого ресурса.

  1. Начните с page=1 и фиксированного limit. При первой загрузке не передавайте updated_since; при следующих — передавайте сохранённую границу предыдущего успешно завершённого цикла.
  2. Из первой успешной страницы запомните meta.generated_at как кандидата для следующего цикла. Не заменяйте его временем последующих страниц.
  3. Примените записи к локальному хранилищу. Пока meta.has_more=true, увеличивайте page на 1. Во всём цикле сохраняйте одинаковые limit и updated_since; фильтры состояния и создания для полной копии не задавайте.
  4. Только после успешного получения и сохранения всех страниц запишите запомненный generated_at как новую границу. Для пустого успешного списка она тоже обновляется.
  5. Следующий цикл снова начните с page=1 и updated_since, равным этой границе без прибавления секунды.

Для новой границы не используйте часы клиента, generated_at последней страницы или максимальный updated_at из записей: так можно пропустить изменения во время обхода или в ту же секунду.

Сопоставляйте записи по (clinic_id, ресурс, id). Обрабатывайте повторные ответы без повторного начисления денег или повторного создания объектов. Для одной и той же записи сравнивайте revision: более старое состояние не должно затирать уже сохранённое новое; повтор той же ревизии должен быть безопасным. После удаления сохраните его ревизию, чтобы запоздалый ответ не восстановил запись. Не используйте наибольшую ревизию одной записи как общую границу: сортировка идёт по ID.

При 429 и 503 повторяйте тот же запрос после паузы из Retry-After, не увеличивая страницу и не сдвигая границу. При 500 используйте повтор с увеличением задержки. Если цикл прервался, последняя завершённая граница остаётся прежней; после восстановления безопасно начать с первой страницы и повторно применить уже полученные записи. Ошибки 401, 403, 404 и 422 требуют проверки ключа, доступа, пути или параметров.

Связанные ресурсы могут временно расходиться: например, оплата уже есть, а контракт ещё создаётся. Страницы не являются единым снимком, а промежуточные события не сохраняются в API. При изменении данных во время обхода продолжайте регулярные циклы опроса до получения актуального состояния.

Пример двух циклов

Первый цикл начинает полную загрузку:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

Допустим, первая страница вернула generated_at=1792577160 и has_more=true. Следующая страница запрашивается без изменения остальных параметров:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'page=2' \
  --data-urlencode 'limit=100'

Когда все страницы сохранены и последняя вернула has_more=false, сохраните 1792577160. Следующий цикл начинается так:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'updated_since=1792577160' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

Удалённые записи

Отметка об удалении возвращается только в списках. Она содержит ровно пять полей:

Поле Тип Описание
id integer, int64 ID удалённой записи в запрашиваемом ресурсе.
clinic_id integer, int64 ID клиники.
deleted boolean Всегда true. Обычные записи вообще не содержат deleted, а не возвращают deleted=false.
revision integer, int64 Номер опубликованного удаления; сравнивается с ревизией той же записи.
updated_at integer, int64 или null Время публикации удаления в Unix timestamp; null, если неизвестно.

Для удалённой заявки GET /consulting-orders/1003 вернёт 404. Отметку нужно получить через список без фильтров состояния/создания, например:

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'updated_since=1792577160' \
  --data-urlencode 'limit=100'
{
  "data": [
    {
      "id": 1003,
      "clinic_id": 7,
      "deleted": true,
      "revision": 47,
      "updated_at": 1792577160
    }
  ],
  "meta": {
    "has_more": false,
    "page": 1,
    "limit": 100,
    "generated_at": 1792577220
  }
}

Полные примеры запросов и ответов

Все люди, номера и идентификаторы в примерах вымышлены, ссылки example.com не ведут к реальным чекам. Это отдельные сценарии, а не единый снимок одной базы. Ответы не сокращены: null и пустые массивы показаны явно. Ключ задаётся во внешней переменной MEDSENGER_API_KEY; не вставляйте его в URL.

Список заявок без связанного платежа

Обычный запрос списка. В показанном сценарии есть одна старая заявка без сохранённого названия/цены услуги и без связанного платежа:

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'limit=100'
{
  "data": [
    {
      "id": 1002,
      "clinic_id": 7,
      "created_at": 1791972000,
      "revision": 43,
      "updated_at": 1792577100,
      "status": "created",
      "reviewed_at": null,
      "service": {
        "captured": false,
        "service_id": null,
        "name": null,
        "duration_days": 7,
        "amount_minor": null,
        "currency": "RUB"
      },
      "duration_days": 7,
      "doctor": {
        "id": 31,
        "name": "Анна Примерова"
      },
      "customer": {
        "name": "Иван Примеров",
        "email": "patient@example.com",
        "phone": null
      },
      "payment": null,
      "contract_id": null,
      "contract": null
    }
  ],
  "meta": {
    "has_more": false,
    "page": 1,
    "limit": 100,
    "generated_at": 1792577160
  }
}

Одна оплаченная заявка

Платёж 3001 имеет авансовый и итоговый чеки, а контракт 2001 закрыт с подтверждением услуги:

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders/1001' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY"
{
  "data": {
    "id": 1001,
    "clinic_id": 7,
    "created_at": 1791972000,
    "revision": 41,
    "updated_at": 1792577100,
    "status": "accepted",
    "reviewed_at": 1791972120,
    "service": {
      "captured": true,
      "service_id": 12,
      "name": "Наблюдение в течение 7 дней",
      "duration_days": 7,
      "amount_minor": 150000,
      "currency": "RUB"
    },
    "duration_days": 7,
    "doctor": {
      "id": 31,
      "name": "Анна Примерова"
    },
    "customer": {
      "name": "Иван Примеров",
      "email": "patient@example.com",
      "phone": null
    },
    "payment": {
      "id": 3001,
      "amount_minor": 150000,
      "currency": "RUB",
      "provider": "sberpay",
      "environment": "production",
      "is_paid": true,
      "paid_at": 1791972060,
      "status": "paid",
      "issue": null,
      "fulfillment_status": "done",
      "external_id": "example-bank-order-3001",
      "fiscalization": {
        "enabled_for_order": true,
        "mode": "advance",
        "provider": "ofd_ferma",
        "environment": "production",
        "receipts": [
          {
            "id": 4001,
            "kind": "advance",
            "status": "confirmed",
            "external_id": "example-receipt-4001",
            "receipt_url": "https://example.com/receipts/4001",
            "error_code": null,
            "fiscal_document": {
              "fiscal_drive_number": "9999078900000001",
              "document_number": "101",
              "fiscal_sign": "1234567890",
              "registered_at": 1791972090
            }
          },
          {
            "id": 4002,
            "kind": "settlement",
            "status": "confirmed",
            "external_id": "example-receipt-4002",
            "receipt_url": "https://example.com/receipts/4002",
            "error_code": null,
            "fiscal_document": {
              "fiscal_drive_number": "9999078900000001",
              "document_number": "102",
              "fiscal_sign": "1234567890",
              "registered_at": 1792577040
            }
          }
        ]
      }
    },
    "contract_id": 2001,
    "contract": {
      "id": 2001,
      "status": "closed",
      "starts_at": 1791972120,
      "ends_at": 1792576920,
      "activated_at": 1791972120,
      "is_delayed": false,
      "awaiting_conclusion": false,
      "concluded_at": 1792576980,
      "service_completed_at": 1792576980,
      "service_completed_by": {
        "type": "doctor",
        "id": 131
      }
    }
  }
}

Список контрактов с платежами и чеками

Основной платёж 3001 совпадает с платежом заявки. Дополнительный счёт 3002 на 500,00 ₽ оформлен без облачной кассы Медсенджера. Первоначальная цена услуги не является суммой всех последующих счетов:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'limit=100'
{
  "data": [
    {
      "id": 2001,
      "status": "closed",
      "starts_at": 1791972120,
      "ends_at": 1792576920,
      "activated_at": 1791972120,
      "is_delayed": false,
      "awaiting_conclusion": false,
      "concluded_at": 1792576980,
      "service_completed_at": 1792576980,
      "service_completed_by": {
        "type": "doctor",
        "id": 131
      },
      "clinic_id": 7,
      "number": "2026/2001",
      "created_at": 1791972120,
      "revision": 42,
      "updated_at": 1792577100,
      "consulting_order_id": 1001,
      "patient": {
        "id": 51,
        "name": "Иван Примеров",
        "email": "patient@example.com",
        "phone": null
      },
      "service": {
        "captured": true,
        "service_id": 12,
        "name": "Наблюдение в течение 7 дней",
        "duration_days": 7,
        "amount_minor": 150000,
        "currency": "RUB"
      },
      "main_doctor": {
        "id": 31,
        "name": "Анна Примерова"
      },
      "responsible_doctor": {
        "id": 31,
        "name": "Анна Примерова"
      },
      "contract_type": {
        "id": 9,
        "name": "Дистанционное наблюдение"
      },
      "is_eternal": false,
      "payments": [
        {
          "id": 3001,
          "amount_minor": 150000,
          "currency": "RUB",
          "provider": "sberpay",
          "environment": "production",
          "is_paid": true,
          "paid_at": 1791972060,
          "status": "paid",
          "issue": null,
          "fulfillment_status": "done",
          "external_id": "example-bank-order-3001",
          "fiscalization": {
            "enabled_for_order": true,
            "mode": "advance",
            "provider": "ofd_ferma",
            "environment": "production",
            "receipts": [
              {
                "id": 4001,
                "kind": "advance",
                "status": "confirmed",
                "external_id": "example-receipt-4001",
                "receipt_url": "https://example.com/receipts/4001",
                "error_code": null,
                "fiscal_document": {
                  "fiscal_drive_number": "9999078900000001",
                  "document_number": "101",
                  "fiscal_sign": "1234567890",
                  "registered_at": 1791972090
                }
              },
              {
                "id": 4002,
                "kind": "settlement",
                "status": "confirmed",
                "external_id": "example-receipt-4002",
                "receipt_url": "https://example.com/receipts/4002",
                "error_code": null,
                "fiscal_document": {
                  "fiscal_drive_number": "9999078900000001",
                  "document_number": "102",
                  "fiscal_sign": "1234567890",
                  "registered_at": 1792577040
                }
              }
            ]
          }
        },
        {
          "id": 3002,
          "amount_minor": 50000,
          "currency": "RUB",
          "provider": "sberpay",
          "environment": "production",
          "is_paid": true,
          "paid_at": 1791972300,
          "status": "paid",
          "issue": null,
          "fulfillment_status": "done",
          "external_id": "example-bank-order-3002",
          "fiscalization": {
            "enabled_for_order": false,
            "mode": null,
            "provider": null,
            "environment": null,
            "receipts": []
          }
        }
      ]
    }
  ],
  "meta": {
    "has_more": false,
    "page": 1,
    "limit": 100,
    "generated_at": 1792577160
  }
}

Один контракт без заявки и платежей

Отложенный контракт может существовать независимо от онлайн-оплаты. Неизвестные/недоступные связанные объекты представлены null:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts/2002' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY"
{
  "data": {
    "id": 2002,
    "status": "waiting_activation",
    "starts_at": 1791972120,
    "ends_at": 1792576920,
    "activated_at": null,
    "is_delayed": true,
    "awaiting_conclusion": false,
    "concluded_at": null,
    "service_completed_at": null,
    "service_completed_by": null,
    "clinic_id": 7,
    "number": null,
    "created_at": 1791972120,
    "revision": 44,
    "updated_at": 1792577100,
    "consulting_order_id": null,
    "patient": null,
    "service": {
      "captured": true,
      "service_id": 12,
      "name": "Наблюдение в течение 7 дней",
      "duration_days": 7,
      "amount_minor": 150000,
      "currency": "RUB"
    },
    "main_doctor": null,
    "responsible_doctor": null,
    "contract_type": null,
    "is_eternal": false,
    "payments": []
  }
}

Оплата есть, контракт ещё создаётся

Полный ответ показывает независимость факта оплаты, действий после оплаты и готовности контракта:

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders/1001' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY"
{
  "data": {
    "id": 1001,
    "clinic_id": 7,
    "created_at": 1791972000,
    "revision": 45,
    "updated_at": 1792577100,
    "status": "payment_required",
    "reviewed_at": null,
    "service": {
      "captured": true,
      "service_id": 12,
      "name": "Наблюдение в течение 7 дней",
      "duration_days": 7,
      "amount_minor": 150000,
      "currency": "RUB"
    },
    "duration_days": 7,
    "doctor": {
      "id": 31,
      "name": "Анна Примерова"
    },
    "customer": {
      "name": "Иван Примеров",
      "email": "patient@example.com",
      "phone": null
    },
    "payment": {
      "id": 3001,
      "amount_minor": 150000,
      "currency": "RUB",
      "provider": "sberpay",
      "environment": "production",
      "is_paid": true,
      "paid_at": 1791972060,
      "status": "paid",
      "issue": null,
      "fulfillment_status": "pending",
      "external_id": "example-bank-order-3001",
      "fiscalization": {
        "enabled_for_order": false,
        "mode": null,
        "provider": null,
        "environment": null,
        "receipts": []
      }
    },
    "contract_id": null,
    "contract": null
  }
}

Ошибки и ограничения

Ошибка содержит объект error с тремя полями:

Поле Тип Описание
error.code string Стабильный машинный код из таблицы ниже. Используйте для ветвления логики.
error.message string Локализованное сообщение. Формулировка и язык могут меняться.
error.details object Дополнительные сведения. При ошибке поля — имя параметра и массив локализованных сообщений. Может быть пустым объектом, в том числе при неизвестном параметре или неверном порядке дат.
HTTP error.code Причина и действие
401 unauthorized Ключ отсутствует, имеет неверный формат, неизвестен или перевыпущен. Проверьте Authorization.
403 api_disabled API отключён системой или клиникой. Проверьте оба разрешения.
404 not_found Неизвестный путь, отсутствующая, удалённая или чужая запись.
405 method_not_allowed Разрешены только GET и HEAD.
422 invalid_parameters Ошибка параметров списка, неизвестный параметр или начало интервала позже конца. Исправьте запрос.
429 rate_limited Превышен общий лимит клиники. Повторите запрос после Retry-After.
503 export_preparing Выгрузка изменений ещё готовится. Повторите запрос после Retry-After. Возможен для списка и отдельной записи.
500 internal_error Внутренняя ошибка. Повторите с задержкой, сохраняя прежнюю границу синхронизации.

Лимит по умолчанию — 120 запросов в минуту на клинику, общий для обоих ресурсов, списков и отдельных записей. HEAD также учитывается. Частота запросов не зависит от размера страницы.

429 и 503 содержат Retry-After — время ожидания в секундах (в текущей реализации 60). 401 содержит WWW-Authenticate: Bearer; 405 — Allow: GET, HEAD. Заголовок Cache-Control: no-store, private присутствует и у ошибок.

Пример ошибки валидации

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'limit=501'

HTTP 422; текст вложенного сообщения показан как пример, а не как стабильная строка:

{
  "error": {
    "code": "invalid_parameters",
    "message": "Некорректные параметры запроса.",
    "details": {
      "limit": [
        "Значение поля limit должно быть не больше 500."
      ]
    }
  }
}

Неизвестный параметр также даёт 422, но details может быть пустым:

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'is_paid=1'
{
  "error": {
    "code": "invalid_parameters",
    "message": "Некорректные параметры запроса.",
    "details": {}
  }
}

Пример временной неготовности выгрузки

При запросе любого ресурса возможен ответ:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Cache-Control: no-store, private
Retry-After: 60
{
  "error": {
    "code": "export_preparing",
    "message": "Данные подготавливаются. Повторите запрос позже.",
    "details": {}
  }
}

При 429 используется тот же порядок повтора; тело:

{
  "error": {
    "code": "rate_limited",
    "message": "Слишком много запросов. Повторите запрос позже.",
    "details": {}
  }
}

Пример отсутствующей или удалённой записи

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders/1003' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY"

HTTP 404:

{
  "error": {
    "code": "not_found",
    "message": "Запись не найдена.",
    "details": {}
  }
}