Перейти к основному содержанию
Заказ набора для домашнего теста отправляет пациенту почтой набор для самостоятельного тестирования. Aniva высылает набор, пациент самостоятельно берет образец дома и отправляет его обратно по почте. Это отличается от записи, при которой медицинский специалист проводит забор венозной крови в пункте тестирования.
Эндпоинтам заказов наборов для домашних тестов требуется право доступа home_kit_orders_view (чтение) или home_kit_orders_manage (запись). Активация также принимает более узкое право доступа home_kit_orders_activate. Получение результатов и Отправка результатов по email дополнительно требуют results_view — доступ к лабораторным результатам и документам всегда ограничен им.

Поля

string
обязательно
UUID, автоматически созданный Aniva. Используй его, чтобы обновить заказ, заменить его панель, активировать его, отменить и получить результаты.
string
обязательно
UUID профиля, к которому относится этот заказ набора для домашнего теста.
string
обязательно
Текущий статус жизненного цикла. Одно из значений: pending, dispatched, activated или cancelled. См. Жизненный цикл ниже. Статус готовности лабораторных результатов (in_progress или completed) определяется через Получение результатов.
object
обязательно
Адрес для почтовой отправки набора — один из двух вариантов: либо {location_id} со ссылкой на известный пункт тестирования, либо поля адреса напрямую (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email необязательны — те же поля, что и в API локаций). Укажи ровно один вариант — ссылку на пункт тестирования или адрес напрямую, но не оба сразу.
Packstation или Postfiliale (только Германия): укажи в street значение Packstation или Postfiliale, в house_number — трехзначный номер станции, а в address_line_2 — DHL Postnummer получателя (6–10 цифр, пробелы допускаются). Без Postnummer оформить отправку посылки невозможно. Postfach не поддерживается.
string
обязательно
Метка времени создания заказа набора для домашнего теста в формате ISO 8601.
string
Метка времени последнего обновления в формате ISO 8601. Null, если заказ набора для домашнего теста никогда не обновлялся.
object
Полный объект профиля пациента, встроенный в каждый ответ по заказу набора для домашнего теста.
object[]
Панель, привязанная к заказу набора для домашнего теста — всегда ровно одна запись вида { panel_id, added_at }, поскольку набор для домашнего теста соответствует физическому набору 1:1. Сверь panel_id со Списком панелей.
object[]
Биомаркеры, добавленные к заказу набора для домашнего теста вне его панели. Каждая запись имеет вид { biomarker_id, added_at }. Сверь каждый biomarker_id со Списком биомаркеров при home_kit=true. В обычном заказе это отдельные тесты в дополнение к панели; в наборе на замену — это то, что лаборатория проверяет повторно.
string
Заказ набора для домашнего теста, который заменяет этот заказ, если это набор на замену. null в обычном заказе.
string
Причина отправки замены в одном предложении. null в обычном заказе.
string[]
Адреса в нижнем регистре, на каждый из которых придет одно письмо, когда все лабораторные результаты будут окончательно готовы. Всегда присутствует — пустое, если отключено. Задай его при создании или обновлении. См. Письма о готовности результатов.
object
Твои собственные пары ключ/значение, которые возвращаются без изменений и не интерпретируются Aniva. Всегда присутствует при чтении — {}, если ничего не задано. Не более 20 ключей; ключи должны соответствовать [A-Za-z0-9_-] и содержать не более 40 символов; значения — строка, число или логическое значение, при этом строки не длиннее 500 символов; общий размер после сериализации — не более 16 384 байта. Ключи, начинающиеся с aniva_, зарезервированы. При обновлении метаданные объединяются: пропущенные ключи сохраняются, ключ со значением null удаляется, а {} очищает все. Валидация проходит целиком или отклоняется полностью. Никогда не указывай персональные или клинические данные в metadata — они не обрабатываются как данные пациента.
string
Лабораторный код образца. Один код, три роли: под ним приходят результаты из лаборатории, он напечатан на физическом наборе, и его же пациент считывает с коробки как код активации. Назначается при упаковке набора — имеет значение null, пока заказ в статусе pending, кроме случаев повторной отправки набора Aniva (см. Жизненный цикл). Всегда только для чтения. Найти заказ по имеющемуся набору можно через GET /api/v1/home-kit-orders?lab_code=….
string
Метка времени взятия образца, переданная через Активацию, — момент, когда пациент фактически собрал образец, в формате UTC. null, пока набор не активирован. Именно это время взятия образца указывается в отчете лаборатории.
object[]
Посылки, связанные с этим заказом, от самой ранней к более поздней, каждая в виде { id, added_at } — набор на пути к пациенту и, для наборов с отслеживанием обратной доставки, образец на пути обратно в лабораторию, которые появляются в момент печати этикеток. Пустой массив, пока заказ в статусе pending, кроме случаев повторной отправки набора Aniva. Получи полные данные о посылках за один запрос с помощью GET /api/v1/shipments?home_kit_order_id={id} — см. Отправления.

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

У заказов наборов для домашних тестов есть четыре состояния жизненного цикла:
Когда Aniva повторно отправляет потерянный набор, заказ возвращается в pending, но сохраняет свой lab_code и предыдущие посылки в shipments. На новом наборе указан тот же код. В новую коробку вкладывают неиспользованный ярлык возврата. Эти два перехода выполняет только Aniva — в API их нет. При каждом переходе отправляется вебхук home_kit_order.pending или home_kit_order.cancelled.
Статусы заказа набора для домашнего теста намеренно укрупнены. Ход доставки к пациенту и обратно отслеживается в отправлениях заказа — dispatched означает, что у набора есть ярлык и лабораторный код, а не то, что он уже в пути; об этом говорит поле status исходящего отправления. Обработка лабораторных результатов происходит на уровне заявок. Готовность результатов (in_progress или completed) доступна через Получение результатов — поле status верхнего уровня остаётся in_progress, пока не закроется каждая заявка, затем переходит в completed — или в fault, если все заявки завершились ошибкой без результатов.

Отслеживание посылок

Что именно возвращается, зависит от набора. Набор для анализа крови после упаковки в Aniva представлен двумя отправлениями: посылкой от Aniva к пациенту и посылкой от пациента в лабораторию (в её destination указана лаборатория), связанными через paired_with. Обратная посылка остаётся в статусе pending — при этом её трек-номер уже известен — пока пациент не отправит её. Набор для анализа микробиома кишечника представлен одним отправлением: доставкой набора пациенту. Его обратный конверт уже оплачен и не отслеживается, поэтому на обратный путь ничего не оформляется. Поле booked_by показывает, кто оформил ярлык: "aniva" или "external". Изменять здесь можно только посылку "aniva", а после печати ярлыка — только её notes. Каждая посылка содержит полный список status_updates от службы доставки, включая detail_code от DHL при перенаправлении в почтовое отделение. В home_kit_orders у отправления перечислены только заказы из твоего контекста доступа. См. Доступ.
Состав заказа набора для домашнего теста можно менять, только пока он в статусе pending. Как только заказ переходит в dispatched (или дальше — activated/cancelled), замена панели и эндпоинты /biomarkers возвращают 409 Conflict: физический набор собирается под выбранную панель, поэтому его состав фиксируется в момент отправки пациенту. Если тебе всё же нужно изменить анализы в уже зафиксированном заказе, свяжись с Aniva напрямую — обычно это ещё возможно, и мы внесём изменения сами, чтобы состав набора оставался согласованным. Если набор уже использован и по нему не удалось получить результаты, закажи вместо этого набор на замену.

Список заказов наборов для домашнего теста

Получи все заказы наборов для домашнего теста, доступные твоему API-ключу:
При необходимости передай ?profile_id={uuid}, чтобы отфильтровать по конкретному профилю, или ?lab_code={code}, чтобы найти заказ по физическому набору в руках — это естественный первый шаг при активации.

Создание заказа набора для домашнего теста

Оформи заказ набора для домашнего теста для профиля пациента:
Передай profile_id, delivery_address и один panel_id. Заказ создаётся в статусе pending. Передай необязательный заголовок Idempotency-Key, чтобы повторный запрос не заказал второй набор — см. Идемпотентность. Ровно одна панель, потому что набор для домашнего теста соответствует физическому набору 1:1 — панель и есть набор. Заказать можно только панели, которые Aniva настроила как наборы для домашнего теста; любая другая панель отклоняется с кодом 422. Панель обязательна при создании, поскольку заказ сразу попадает в очередь на упаковку и сборка может начаться немедленно. Пока заказ в статусе pending, панель можно заменить через Обновление. Чтобы отправить второй набор взамен того, по которому не удалось получить результаты, передай replaces_home_kit_order_id вместо выбора панели — см. Наборы на замену.

Наборы на замену

Иногда по набору не удаётся получить результаты: пациент не смог наполнить пробирку, в образце оказалось слишком мало материала, лаборатория не смогла проанализировать его часть. Закажи для него замену:
Замена — это новый заказ с новым лабораторным кодом, даже если первый набор так и не был активирован: лаборатории нужно новое направление, а два образца под одним кодом невозможно различить. Оба заказа остаются доступны для чтения и связаны через replaces_home_kit_order_id. Заказ, который ты заменяешь, остаётся нетронутым. Он сохраняет свой статус, лабораторный код и все уже загруженные результаты, поэтому если пациент всё-таки отправит первый набор, он получит всё, что лаборатория сможет из него прочитать. Панель наследуется. Не передавай panel_id, и замена получит панель заменяемого заказа — именно её купил пациент и под неё оформлена коробка. Передавай другую панель только при замене всей панели целиком; указание панели вместе с подмножеством маркеров отклоняется с кодом 422, потому что подмножество имеет смысл только в рамках той панели, из которой оно выбрано. Панель заказа на замену также нельзя поменять позже. Ты выбираешь, что пересдать. Передай в biomarker_ids маркеры, которые не получились, и лаборатория выполнит повторно только их — в наборе придут только нужные пробирки. Не передавай это поле, чтобы повторить всю панель целиком — это правильный выбор, если не удалось проанализировать вообще ничего. Для этого не нужен дополнительный scope: повторный анализ уже оплаченных пациентом маркеров не считается заказом отдельных анализов. Удалить эти маркеры потом нельзя, потому что из них и состоит всё направление.
Маркеры пересдаются группами панели, а не по одному. Если указать один маркер из группы, повторно выполняется вся группа, потому что нельзя оформить заказ в лабораторию, который вернёт больше данных, чем запрошено. Поэтому замена для одного маркера может вернуть несколько результатов, а количество пробирок может оказаться больше, чем можно ожидать по списку маркеров.
В пути одновременно может находиться только одна замена для одного набора — пока замена в статусе pending или dispatched, повторное создание замены для того же заказа вернёт 409 с указанием этой замены. Результаты приходят под собственным lab_code замены через её Получение результатов. Замена не подходит для посылки, которая так и не дошла. Вместо этого напиши в Aniva: в таком случае делается повторная отправка того же заказа с тем же лабораторным кодом, а не новый заказ.

Обновление заказа набора для домашнего теста

Измени адрес доставки, замени панель, обнови свои метаданные или замени адреса для писем о готовности результатов:
Передавай только те поля, которые хочешь изменить. Поле panel_id заменяет прикреплённую панель — поскольку в наборе ровно одна панель, замена является единственной осмысленной операцией, поэтому эндпоинтов для добавления и удаления панелей нет. Адрес и панель можно менять, только пока заказ в статусе pending; поле metadata доступно для записи на протяжении всей жизни заказа. Поле results_ready_emails доступно для записи, пока заказ не перейдёт в cancelled.

Отмена заказа набора для домашнего теста

Отмени заказ набора для домашнего теста, который больше не нужен:
Это переводит заказ набора для домашнего теста в статус cancelled. В ответе возвращается отменённый заказ. Отменить можно только заказ в статусе pending. Начиная с dispatched набор уже упакован и промаркирован — автоматического отзыва нет — и запрос возвращает 409. Если нужно остановить уже отправленный набор, свяжись с Aniva напрямую. Отмена заказа в статусе pending, набор для которого уже заказан у фулфилмента, отменяет его и там, и запрос завершается успешно, только если фулфилмент подтвердит отмену:
  • 409 — набор уже упакован и промаркирован, поэтому отозвать его больше нельзя, даже если у заказа ещё стоит статус pending.
  • 502 — фулфилмент отклонил отмену (в ошибке указана причина) или не отвечает. Ничего не изменилось — заказ по-прежнему активен, и его можно отменить повторно.
Если отмена вернула ошибку, заказ остаётся точно таким же, как был, поэтому только код 200 подтверждает, что набор не будет отправлен. Отмена уже отменённого заказа (cancelled) возвращает тот же код 200, независимо от того, из какого статуса он был отменён.

Активация заказа набора для домашнего теста

Когда пациент соберёт образец, сообщи об этом:
Передай activated_at — момент фактического сбора образца пациентом в формате времени UTC. Именно это время сбора попадёт в лабораторный отчёт, поэтому передавай реальный момент сбора, а не время обработки запроса на твоей стороне. Активация необратима: заказ переходит в статус activated, после чего его нельзя ни отменить, ни изменить. Это аналог Подтверждения забора крови для набора для домашнего теста, но без штрихкода — код наносится на набор при упаковке, поэтому тебе не нужно его знать. К этому моменту у заказа уже должен быть lab_code; заказ без него вернёт 409. Активация также оформляет заказ в лаборатории: панель набора заказывается в лаборатории под его lab_code, чтобы отправленный обратно образец уже ожидали, а результаты прикреплялись по мере их поступления. Это выполняется уже после отправки ответа, а любые сбои на стороне лаборатории обрабатывает Aniva, не возвращая ошибку на твой запрос.

Отдельные биомаркеры

К заказу набора для домашнего теста можно добавить отдельные биомаркеры как дополнительные анализы сверх панели. Это удобно, когда к набору нужен индивидуальный подбор показателей. Добавленные биомаркеры отображаются в ответе заказа набора для домашнего теста в виде массива individual_biomarkers (на одном уровне с panels). Оба эндпоинта для биомаркеров требуют scope home_kit_orders_individual_biomarker_selection в дополнение к home_kit_orders_manage — наборы для домашнего теста заказываются по панелям, поэтому отдельные маркеры включаются индивидуально для каждого партнёра. Обратись в Aniva, если это нужно твоей интеграции. Добавь биомаркеры (идемпотентно — уже привязанные биомаркеры сохраняются):
Удаление биомаркеров (идемпотентно — непривязанный ID игнорируется):
Оба эндпоинта принимают массив biomarker_ids. Используй Список биомаркеров с home_kit=true, чтобы узнать ID биомаркеров. Биомаркеры можно менять, только пока набор в статусе pending (см. Жизненный цикл).

Получение лабораторных результатов

Когда лаборатория обработает возвращённый образец, получи клинические и генетические результаты:
Ответ включает запланированные тесты (статус planned) наряду с полученными результатами, поэтому ты можешь отслеживать, что ещё ожидается. Результаты привязаны к lab_code заказа и приходят маркер за маркером по мере анализа в лаборатории, поэтому частичные ответы — это нормально. Поле верхнего уровня status имеет значение in_progress до итогового отчёта, затем completed (или fault, если все лабораторные заказы завершились сбоем без отчёта) — используй его, чтобы определить, завершена ли лабораторная обработка заказа набора для домашнего теста. Вебхук home_kit_order.results.completed сообщит тебе, когда это произойдёт, так что опрашивать API не нужно. Ссылки на PDF-отчёты лаборатории указаны в массиве documents — используй GET /api/v1/documents/{id}, чтобы их скачать.

Пример заказа набора для домашнего теста