YouEDC Capture

API для МИС, лабораторий и систем спонсора

Ключ на систему, что ей можно писать и читать, вызовы с примерами, аудит.

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

Ключи

Менеджер исследования открывает в меню исследования пункт API и делает ключ для каждой системы: её название («Лаборатория центра 01»), что ей можно (запись, чтение или и то и другое), центры, с которыми она работает, может ли она включать новых пациентов и сколько ключ действует (30, 90 или 365 дней). Ключ показывается один раз: скопируйте его в настройки системы. Портал хранит только его отпечаток, поэтому потерянный ключ показать заново нельзя; сделайте новый и отзовите старый.

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

1. Прочитать схему

Сначала система запрашивает схему исследования: центры своего ключа, визиты, формы и коды их полей с типами, единицами, диапазонами и вариантами ответа. Коды те же, что в конструкторе эИРК и в выгрузке.

curl https://youedc.com/api/v1/studies/REG-DIAB-01 \
  -H "Authorization: Bearer yk_…"

2. Включить пациента

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

curl https://youedc.com/api/v1/studies/REG-DIAB-01/patients \
  -H "Authorization: Bearer yk_…" -H "Content-Type: application/json" \
  -d '{"site": "01", "sex": "F", "birth_year": 1961, "enrolled_on": "2026-10-05"}'

→ 201 {"subject": "REGDIA-01-0031", "site": "01"}

3. Отправить формы визитов

В одном запросе до 500 записей. Запись называет пациента, визит, форму и значения по кодам полей; instance — номер повтора визита, status — complete (по умолчанию) или draft. Уже заполненная форма пропускается, если в записи нет "update": true; тогда каждое изменённое значение попадает в аудит.

Пример: лаборатория демо-регистра REG-DIAB-01 присылает результаты визита «Месяц 6». HbA1c 11,8% выше ожидаемого диапазона, поэтому вторая запись загружается, и для центра 02 открывается автоматический запрос, как если бы значение ввели вручную.

curl https://youedc.com/api/v1/studies/REG-DIAB-01/records \
  -H "Authorization: Bearer yk_…" -H "Content-Type: application/json" \
  -d '{"records": [
        {"subject": "REGDIA-01-0004", "visit": "Месяц 6", "form": "LB",
         "values": {"LB_DATE": "2026-09-28", "HBA1C": "7.4", "GLUC": "6.8"}},
        {"subject": "REGDIA-02-0004", "visit": "Месяц 6", "form": "LB",
         "values": {"LB_DATE": "2026-09-29", "HBA1C": "11.8", "GLUC": "9.1"}}
      ]}'

→ 200 {"results": [{"index": 0, "status": "ok", "message": "Loaded."},
                   {"index": 1, "status": "warn", "message": "Loaded. Automatic queries: 1."}],
       "counts": {"ok": 1, "warn": 1, "skip": 0, "error": 0}}

4. Забрать данные

Ключ с правом чтения забирает данные исследования в хранилище спонсора, статистическую программу или CTMS. Его делает менеджер, у которого есть право выгрузки данных; при создании ключа выберите «Чтение» или «Запись и чтение». Ключ видит то же, что выгрузка: только свои центры, без форм для расслепленной команды, если сделавший ключ не расслеплен, и без пациентов, отозвавших согласие на использование данных. Электронной почты, PIN, даты рождения и инициалов пациента в ответах нет.

GET …/patients — пациенты: номер, центр, пол, год рождения, дата включения, статус.
GET …/records — сохранённые формы со значениями по кодам полей, отметками ND/UNK/NA и строками таблиц. Фильтры: subject, site, visit, form, status.
GET …/queries — запросы с полем, формой, визитом и статусом.

Ответ приходит страницами до 1000 строк (limit, по умолчанию 500). Если в ответе есть next, передайте его в after, чтобы получить следующую страницу. Чтобы каждую ночь забирать только изменения, добавьте updated_since со временем прошлой загрузки.

curl "https://youedc.com/api/v1/studies/REG-DIAB-01/records?form=LB&updated_since=2026-10-08T00:00:00Z" \
  -H "Authorization: Bearer yk_…"

→ 200 {"records": [{"id": 5120, "subject": "REGDIA-01-0004", "site": "01", "visit": "Месяц 6",
                    "form": "LB", "instance": 1, "status": "complete", "source": "import",
                    "updated_at": "2026-10-08T07:12:40Z",
                    "values": {"LB_DATE": "2026-09-28", "HBA1C": "7.4", "GLUC": "6.8"}, "not_done": {}}],
       "next": null}

Описание всех вызовов в формате OpenAPI 3.1 лежит по адресу /api/v1/openapi.json: из него программист системы сделает клиент или откроет его в любом просмотрщике OpenAPI.

5. Отправить медицинскую запись пациента в FHIR R4

МИС, которая выгружает HL7 FHIR R4, отправляет запись пациента как есть, без собственного сопоставления: Bundle, отдельный ресурс или NDJSON, до 5 МБ, на POST …/fhir?subject=<номер пациента>. Куда попадут результаты анализов, витальные показатели, заболевания и препараты, решает сопоставление FHIR исследования. По умолчанию (mode=review) ничего не сохраняется: ответ перечисляет каждое значение с его местом в eCRF, а импорт ждёт на карточке пациента, пока команда центра его проверит и подтвердит. С mode=save ключ сам сохраняет значения, которые заполняют пустые места, и новые записи — от имени того, кто сделал ключ; значение, которое изменило бы сохранённое, так никогда не сохраняется и остаётся на проверку центру.

curl "https://youedc.com/api/v1/studies/DEMO-CKD/fhir?subject=CK-01-0004" \
  -H "Authorization: Bearer yk_…" -H "Content-Type: application/fhir+json" \
  --data-binary @record.json

→ 201 {"import": "FH-2", "subject": "CK-01-0004", "status": "proposed",
       "counts": {"values": 4, "conflicts": 1, "same": 0, "skipped": 1},
       "review_url": "https://youedc.com/p/DEMO-CKD/s/CK-01-0004/fhir/2",
       "items": [{"resource": "Observation/lab-creat-1", "code": "LOINC 2160-0", "form": "LAB",
                  "field": "CREAT", "value": "203", "state": "conflict", …}, …]}

Файл другого пациента, два пациента в одном файле, тело, которое не является FHIR JSON, и файл больше 5 МБ отклоняются (422 или 413), и ничего не сохраняется.

Ответы и ошибки

У каждой записи свой ответ: ok — загружено, warn — загружено с автоматическими запросами или черновиком, skip — уже заполнено, error — не загружено, с причиной.
Весь запрос отклоняется с кодом 401 (нет ключа, ключ неверный, отозван или истёк), 403 (ключу нельзя писать, читать или включать пациентов, или API выключен), 400 (неверный фильтр чтения), 422 (нет такой формы или визита), 404 (другое исследование), 413 (больше 500 записей), 423 (база закрыта или набор закрыт) или 429 (больше 600 запросов в минуту).
Сообщения на английском; добавьте ?lang=ru или заголовок Accept-Language: ru, чтобы получить их по-русски.

Безопасность и аудит

Каждое изменение попадает в аудит с именем ключа как автором, например «Лаборатория центра 01 (API)», и причиной «Отправлено через ключ API …». Выдача и отзыв ключей тоже записываются.
Каждое чтение записывается в журнал: какой ключ, когда, какой вызов с какими фильтрами и сколько строк он отдал. Последние чтения видны внизу страницы API, а в таблице ключей — сколько строк прочитал каждый ключ.
Ключ на чтение перестаёт работать, если у сделавшего его менеджера отняли право выгрузки данных.
Если исследование требует согласия до ввода данных, данные пациента без действующего согласия не загружаются.
В слепом исследовании ключ видит и пишет формы для расслепленной команды, только если расслеплен менеджер, сделавший ключ.
Передавайте ключи только по HTTPS и храните их в настройках системы, а не в письмах и документах.