Перейти к основному содержанию
Запись — это запланированный забор крови для профиля пациента в физической локации для сдачи анализов, который проводит медицинский специалист. Наборы, отправленные пациенту по почте, не являются записями — см. Заказы наборов для домашнего теста.

Поля

string
обязательно
UUID, автоматически сгенерированный Aniva. Используй его, чтобы добавлять панели, подтверждать забор крови и получать результаты.
string
обязательно
UUID профиля, к которому относится эта запись.
string
UUID локации для сдачи анализов, где пройдет забор крови. Наборы для домашнего теста не являются записями — см. Заказы наборов для домашнего теста.
string
Запланированные дата и время забора крови в формате ISO 8601. Всегда возвращается в UTC с суффиксом Z (например, 2026-04-15T08:30:00Z). При создании или обновлении значение должно содержать обозначение часового пояса (Z или явное смещение вроде +02:00) — даты и время без часового пояса отклоняются. Время должно быть в будущем, а в локациях под управлением Aniva — не менее чем за 12 часов (минимальный срок до записи).
string
обязательно
Текущий статус жизненного цикла. Одно из значений: pending, confirmed, blood_drawn или cancelled. См. Жизненный цикл ниже. Подробный статус готовности лабораторных результатов (in_progress или completed) определяется через Получить результаты; более детальный статус отправления (в пути, доставлено и т. д.) — по каждому элементу встроенного массива shipments в Получить отправление.
string
Причина в свободной форме, указанная при отмене записи (например, неявка, поздняя отмена, «Не удалось. Требуется повтор»). Имеет значение null, если status не равен cancelled.
string[]
обязательно
Адреса в нижнем регистре, на каждый из которых приходит одно письмо, когда все результаты лаборатории готовы. Пустой список, если отключено. См. Письма о готовности результатов.
string
обязательно
Способ забора крови: capillary (из пальца или плеча в микротейнеры) или venous (из вены в пробирки). Используется способ, заданный для записи, иначе default_draw_method её локации. После забора крови здесь указан фактически использованный способ.
string
обязательно
Временная метка создания записи в формате ISO 8601.
string
Временная метка последнего обновления в формате ISO 8601. Null, если запись ни разу не обновлялась.
string[]
обязательно
Лабораторные коды (штрихкоды пробирок), записанные через Подтвердить забор крови, в порядке сканирования. Пусто, пока забор крови не подтвержден. При венозном заборе один код напечатан на каждой пробирке; при капиллярном — свой код на каждом микротейнере. Результаты и документы ссылаются на них через lab_code.
object[]
обязательно
Панели, добавленные к этой записи, в виде элементов { panel_id, added_at }. См. Добавление панелей.
object[]
обязательно
Отдельные биомаркеры, добавленные к этой записи, в виде элементов { biomarker_id, added_at }. См. Отдельные биомаркеры.
object[]
обязательно
Отправления, привязанные к этой записи, в виде элементов { id, added_at }, начиная с самой ранней привязки. См. Привязка отправлений.
object
обязательно
Полный объект профиля пациента, встроенный в каждый ответ по записи. Ниже показана только часть полей. Все поля перечислены в Получить запись.

Жизненный цикл

У записей есть четыре состояния жизненного цикла:
Статус записи намеренно укрупнен — более детальный прогресс доступен через отдельные эндпоинты:
  • Готовность лабораторных результатов → Получить результаты — поле status верхнего уровня имеет значение in_progress или completed.
  • Ход доставки отправления (в пути, доставлено и т. д.) → перейди по каждому элементу встроенного массива shipments в записи к Получить отправление — у каждого отправления есть собственный status и журнал событий status_updates.
Каждое изменение статуса отправляет вебхук вида appointment.*, например appointment.confirmed. Новое время или локация отправляет appointment.rescheduled.
Подтверждение записи (перевод в статус blood_drawn) необратимо. Как только ты передашь лабораторный код (или коды), процесс лабораторного заказа запускается и отменить его нельзя. Обновление и отмена возможны только пока запись находится в статусе pending или confirmed.

Список записей

Получи все записи, доступные твоему 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, отменить нельзя.

Добавление панелей

Перед подтверждением забора крови добавь панели анализов крови, которые ты хочешь выполнить, вызвав:
Передай массив UUID панелей в поле panel_ids. Идентификаторы панелей предоставляет Aniva для твоего партнёрского аккаунта.
Панели нужно добавить до забора крови — то есть пока запись находится в статусе pending или confirmed. После того как запись перейдёт в blood_drawn, ты уже не сможешь добавлять или менять панели.

Удаление панелей

Если тебе нужно удалить панели до забора крови, вызови:
Передай массив UUID панелей в поле 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 и запускает лабораторную обработку. Это действие необратимо.

Забор отправления

Эндпоинт POST /api/v1/appointments/pickup удалён вместе со статусом записи shipment_picked_up. Теперь он возвращает 405 Method Not Allowed, потому что этот путь попадает на маршрут получения записи по идентификатору. На последнем этапе этот эндпоинт работал как заглушка, которая принимала запрос и ничего не делала, поэтому его удаление не меняет поведения, на которое ты рассчитывал.
Чтобы отслеживать дальнейшие этапы после забора крови, переходи по каждому элементу встроенного массива 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}, чтобы скачать их.

Пример записи