Поля
UUID, автоматически сгенерированный Aniva. Используй его, чтобы добавлять панели, подтверждать забор крови и получать результаты.
UUID локации для сдачи анализов, где пройдет забор крови. Наборы для домашнего теста не являются
записями — см. Заказы наборов для домашнего теста.
Запланированные дата и время забора крови в формате ISO 8601. Всегда возвращается в UTC с
суффиксом
Z (например, 2026-04-15T08:30:00Z). При создании или обновлении значение должно
содержать обозначение часового пояса (Z или явное смещение вроде +02:00) — даты и время без
часового пояса отклоняются. Время должно быть в будущем, а в локациях под управлением Aniva — не
менее чем за 12 часов (минимальный срок до записи).Текущий статус жизненного цикла. Одно из значений:
pending, confirmed, blood_drawn или cancelled. См.
Жизненный цикл ниже. Подробный статус готовности лабораторных результатов (in_progress или completed)
определяется через Получить результаты; более детальный статус отправления (в пути,
доставлено и т. д.) — по каждому элементу встроенного массива shipments в
Получить отправление.Причина в свободной форме, указанная при отмене записи (например, неявка, поздняя отмена,
«Не удалось. Требуется повтор»). Имеет значение
null, если status не равен cancelled.Адреса в нижнем регистре, на каждый из которых приходит одно письмо, когда все результаты
лаборатории готовы. Пустой список, если отключено. См.
Письма о готовности результатов.
Способ забора крови:
capillary (из пальца или плеча в микротейнеры) или venous (из вены
в пробирки). Используется способ, заданный для записи, иначе default_draw_method её
локации. После забора крови здесь указан фактически использованный способ.Временная метка последнего обновления в формате ISO 8601. Null, если запись ни разу не обновлялась.
Лабораторные коды (штрихкоды пробирок), записанные через Подтвердить забор крови,
в порядке сканирования. Пусто, пока забор крови не подтвержден. При венозном заборе один код
напечатан на каждой пробирке; при капиллярном — свой код на каждом микротейнере. Результаты и
документы ссылаются на них через
lab_code.Панели, добавленные к этой записи, в виде элементов
{ panel_id, added_at }. См.
Добавление панелей.Отдельные биомаркеры, добавленные к этой записи, в виде элементов
{ biomarker_id, added_at }. См.
Отдельные биомаркеры.Отправления, привязанные к этой записи, в виде элементов
{ id, added_at }, начиная с самой ранней привязки. См.
Привязка отправлений.Полный объект профиля пациента, встроенный в каждый ответ по записи. Ниже показана только часть
полей. Все поля перечислены в Получить запись.
Жизненный цикл
У записей есть четыре состояния жизненного цикла:Статус записи намеренно укрупнен — более детальный прогресс доступен
через отдельные эндпоинты:
- Готовность лабораторных результатов →
Получить результаты — поле
statusверхнего уровня имеет значениеin_progressилиcompleted. - Ход доставки отправления (в пути, доставлено и т. д.) → перейди по каждому элементу
встроенного массива
shipmentsв записи к Получить отправление — у каждого отправления есть собственныйstatusи журнал событийstatus_updates.
appointment.*, например
appointment.confirmed. Новое время или локация отправляет appointment.rescheduled.Список записей
Получи все записи, доступные твоему API-ключу:?profile_id={uuid}, чтобы отфильтровать по конкретному профилю. Без этого параметра применяется временное окно по умолчанию (за последние 2 месяца и на 1 месяц вперед).
Обновление записи
До подтверждения забора крови ты можешь перенести запись или изменить локацию сдачи анализов:scheduled_at, location_id, draw_method и results_ready_emails. Указывай только те поля, которые хочешь изменить.
Способ забора крови
У каждой записи есть полеdraw_method: capillary (из пальца или плеча в микротейнеры) или
venous (из вены в пробирки). Оно относится только к забору крови. Моча, мазки и другие
образцы, кроме крови, собираются одинаково при любом способе.
По умолчанию используется значение default_draw_method локации. Задай draw_method при создании или обновлении,
чтобы выбрать другой способ, или передай null, чтобы вернуться к значению локации по умолчанию. Этот способ должен
быть указан в draw_methods локации, а выбранные анализы должны быть с ним совместимы, иначе запрос вернет 400.
После забора крови изменить его нельзя. После забора крови в draw_method хранится фактически использованный способ.
Одна запись на профиль, локацию и время
У профиля может быть не более одной неотмененной записи на каждую пару(location_id, scheduled_at) —
у одного человека нельзя взять кровь дважды в одном месте и в одно время, независимо от того, сколько
параллельных записей принимает локация.
И Создать запись, и
Обновить запись проверяют это правило и возвращают 409 с
полем appointment_id, указывающим на уже существующую запись. Воспринимай этот ответ как «запись
уже существует», а не как ошибку для повторной попытки: получи, перенеси или отмени указанную запись.
На практике это значит, что повторные запросы на создание безопасны. Запрос, который ты повторно отправляешь после сетевого таймаута
или который пользователь запускает дважды, сводится к одной записи вместо двух — так что тебе
никогда не придётся разбираться с дублями записей для одного и того же пациента постфактум.
Изменения разрешены только до забора крови — то есть пока запись находится в статусе
pending
или confirmed. Как только запись переходит в blood_drawn или отменена (cancelled), её
уже нельзя изменить. Единственное исключение — results_ready_emails: ты всё ещё можешь
изменить это поле отдельно после забора крови.Отмена записи
Отмени запись, которая больше не нужна:cancelled. В ответе возвращается отменённая запись.
При желании передай в теле запроса cancellation_reason (до 500 символов), чтобы указать причину. Она
сохраняется в записи и возвращается как cancellation_reason при последующем чтении.
Отмена разрешена только до забора крови — то есть пока запись находится в статусе
pending или
confirmed. Записи, которые уже перешли в blood_drawn, отменить нельзя.Добавление панелей
Перед подтверждением забора крови добавь панели анализов крови, которые ты хочешь выполнить, вызвав:panel_ids. Идентификаторы панелей предоставляет Aniva для твоего партнёрского аккаунта.
Панели нужно добавить до забора крови — то есть пока запись находится в статусе
pending или
confirmed. После того как запись перейдёт в blood_drawn, ты уже не сможешь добавлять или
менять панели.Удаление панелей
Если тебе нужно удалить панели до забора крови, вызови:panel_ids. Удаление идемпотентно: панель, которая не привязана, игнорируется.
Как и добавление панелей, удаление разрешено только до забора крови — то есть пока запись
находится в статусе
pending или confirmed. После того как запись перейдёт в blood_drawn,
удалить панели уже нельзя.Отдельные биомаркеры
Ты можешь привязать к записи отдельные биомаркеры как самостоятельные анализы, вне готовых панелей. Это удобно, когда специалисту нужен индивидуальный набор вместо готового пакета. Привязанные биомаркеры возвращаются в ответе записи в виде массиваindividual_biomarkers (на одном уровне с panels). Решения по маршрутизации принимаются дальше в конвейере логистики заказов на основе сопоставления каждого биомаркера с лабораториями.
Добавь биомаркеры (идемпотентно — уже привязанные биомаркеры сохраняются):
biomarker_ids и проверяют итоговый набор по правилам полноты каждой лаборатории — заказ, который нельзя корректно оформить (например, соотношение CRP/HDL без CRP и HDL), возвращает 400 с биомаркерами, которые тебе нужно добавить, и ничего не сохраняет. Используй Список биомаркеров, чтобы узнать идентификаторы биомаркеров.
Как и изменения панелей, отдельные биомаркеры можно добавлять или удалять только до забора
крови — то есть пока запись находится в статусе
pending или confirmed. Как только запись
переходит в blood_drawn, пользовательский снимок фиксируется.Предпросмотр необходимых контейнеров
После добавления панелей или отдельных биомаркеров посмотри физические контейнеры для биоматериала, которые понадобятся для сбора образцов:containers в ответе содержит тип, название, цвет крышки, объём, артикул производителя и количество для каждого необходимого контейнера. Это помогает специалистам подготовить нужные материалы перед забором крови. Ответ также содержит объект pricing — общий счёт по всей корзине записи (сработавшие позиции, привязанные панели и по одной строке на каждый предоставляемый биомаркер с ценой по твоему тарифу и розничной ценой рядом; см. Ценообразование), который заполняется, когда к записи привязаны анализы и у твоего ключа есть разрешение prices_view, иначе null. Поле routing намеренно никогда не раскрывается и всегда равно null.
Предпросмотр отражает привязанные на данный момент панели и биомаркеры. Если ты добавишь или
удалишь панели после предпросмотра, вызови эндпоинт предпросмотра снова, чтобы получить обновлённый
список необходимых контейнеров.
Подтверждение забора крови
После забора крови отправь лабораторные коды (штрихкоды пробирок), чтобы запустить конвейер лабораторных заказов:lab_code, если на каждой пробирке напечатан один и тот же код (венозный забор), или
lab_codes с одним элементом на каждый код — для каждого с теми panel_ids, которые он охватывает —
если каждая панель собирается в отдельные пробирки со своим кодом (капиллярный забор). Тогда каждая
панель становится отдельным направлением в лабораторию под своим кодом. Коды возвращаются в поле
lab_codes записи.
При капиллярном заборе кровь распределяется по микротейнерам. Сначала идут панели в порядке
бронирования. Затем отдельные биомаркеры заполняют свободное место в микротейнерах панелей.
Если им нужно больше места, открываются новые микротейнеры. Мы распределяем их равномерно.
Каждый микротейнер вмещает не более 150 µl отдельных биомаркеров. Запросы на изменение панелей
или биомаркеров возвращают 400, если итоговый набор нарушает это правило.
Это переводит запись в статус blood_drawn и запускает лабораторную обработку. Это действие необратимо.
Забор отправления
Чтобы отслеживать дальнейшие этапы после забора крови, переходи по каждому элементу встроенного массиваshipments записи в Получение отправления — у каждого
отправления есть собственный status и история status_updates.
Привязка отправлений
Запись может быть связана с одним или несколькими отправлениями (и наоборот — это связь многие ко многим). Текущий набор связей возвращается напрямую с обеих сторон:- в записи — как массив
shipmentsс элементами{ id, added_at }; - в отправлении — как массив
appointmentsс элементами{ id, added_at }.
id ссылается на канонический эндпоинт
с подробной информацией (Получение отправления /
Получение записи) для получения полного объекта.
Отправления привязываются при создании через поле appointment_id в эндпоинте
Создание отправления. После создания управляй связями со стороны
отправления через эндпоинты Привязка записей к отправлению и
Отвязка записей от отправления; каждый из них
возвращает обновлённый список записей для этого отправления. Чтобы получить полные данные по
посылкам записи, используй Список отправлений с ?appointment_id=.
Правило изменения: связи можно создавать или удалять, если ЛИБО
- по записи уже прошёл забор крови (
blood_drawn), либо - отправление было создано менее 24 часов назад.
Получение лабораторных результатов
Когда лаборатория обработает образцы крови, получи клинические и генетические результаты:planned) наряду с полученными результатами, поэтому ты можешь
отслеживать, что еще ожидается. Поле верхнего уровня status остается in_progress, пока не закроются все заявки,
а затем меняется на completed (или fault, если ни по одной из них не пришли данные) — используй его, чтобы определить,
завершена ли лабораторная работа по записи. Вебхук appointment.results.completed
сообщит тебе, когда это произойдет, поэтому опрашивать API не нужно. Массив
submissions разбивает эти данные по каждому лабораторному направлению, и у каждого есть свой lab_code. Каждый
полученный результат и документ содержит lab_code, под которым он был оформлен. Ссылки на PDF-отчеты лаборатории
находятся в массиве documents — используй GET /api/v1/documents/{id}, чтобы скачать их.