Как подключить API заявок и контрактов?
API передаёт внешней системе, например 1С, актуальные заявки, контракты, платежи и доступные чеки одной клиники. Все методы предназначены только для чтения. API не закрывает контракты, не проводит платежи и не формирует чеки.
Включение и ключ
Сначала системный администратор в /admin открывает редактирование клиники, на вкладке Система включает API доступен клинике и сохраняет изменения. По умолчанию это разрешение выключено. Без него раздел API скрыт в кабинете клиники, управление ключом и запросы API недоступны.
После этого главный администратор клиники открывает Настройки → Общие настройки → API для внешних систем, включает доступ и нажимает Сохранить настройки API. Здесь же можно показать, скопировать и перевыпустить ключ. Обычные администраторы не могут управлять ключом. Клиника не может самостоятельно выдать себе системное разрешение.
Отключение разрешения в /admin сразу скрывает раздел и блокирует запросы по существующему ключу. Ключ и настройка включения обмена сохраняются: после возврата разрешения действует прежнее состояние. Для работы 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 независимо, с отдельной сохранённой временной границей для каждого ресурса.
- Начните с
page=1и фиксированногоlimit. При первой загрузке не передавайтеupdated_since; при следующих — передавайте сохранённую границу предыдущего успешно завершённого цикла. - Из первой успешной страницы запомните
meta.generated_atкак кандидата для следующего цикла. Не заменяйте его временем последующих страниц. - Примените записи к локальному хранилищу. Пока
meta.has_more=true, увеличивайтеpageна 1. Во всём цикле сохраняйте одинаковыеlimitиupdated_since; фильтры состояния и создания для полной копии не задавайте. - Только после успешного получения и сохранения всех страниц запишите запомненный
generated_atкак новую границу. Для пустого успешного списка она тоже обновляется. - Следующий цикл снова начните с
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": {}
}
}