Перейти к основному содержанию
POST
Оформи заказ набора для домашнего теста для профиля пациента. При таком заказе отправляется почтовый набор для самостоятельного тестирования — Aniva высылает набор по адресу доставки, пациент сам собирает образец дома и отправляет его обратно по почте. Это отличается от записи, которая представляет собой венозный забор крови в пункте тестирования. Требуется ровно одна панель. Набор для домашнего теста соответствует физическому набору 1:1 — панель и есть набор, — и заказ попадает в очередь на упаковку сразу после создания, поэтому состав должен быть окончательным заранее. Ты всё ещё можешь заменить панель через Обновление заказа набора для домашнего теста, пока заказ находится в статусе pending.

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

Если по набору не удалось получить результаты — пациент не смог наполнить пробирку, в образце оказалось слишком мало материала, лаборатория не смогла его проанализировать — закажи замену, передав replaces_home_kit_order_id. Замена — это новый заказ с новым лабораторным кодом, даже если первый набор так и не был активирован: лаборатории нужно новое направление, а два образца под одним кодом невозможно отличить друг от друга. Заменяемый заказ остаётся без изменений — он сохраняет свой статус, свой лабораторный код и все результаты, уже привязанные к нему. Из этого следуют две вещи:
  • Панель наследуется. Не передавай panel_id, и замена получит панель заменяемого заказа — именно её купил пациент и под неё брендирована коробка.
  • Ты выбираешь, что повторить. Передай biomarker_ids с маркерами, по которым анализ не удался, и лаборатория повторит только их, поэтому в наборе отправят только нужные пробирки. Не передавай это поле, чтобы повторить всю панель.
Маркеры повторяются группами панели, а не по одному. Указание одного маркера из группы запускает повтор всей группы, потому что нельзя оформить лабораторный заказ, который выдаёт больше, чем было запрошено. Поэтому замена для одного маркера может прийти с несколькими результатами, а пробирок в наборе может быть больше, чем можно ожидать по списку маркеров. Одновременно в пути может быть только одна замена на один набор.
Если твоя интеграция появилась до этих полей, Aniva при создании заказа также считывает metadata.original_kit_id и metadata.replacement_reason и обрабатывает заказ как замену. Это единственное место, где метаданные интерпретируются: оно нужно только для поддержки старой интеграции, а поля выше всегда имеют приоритет. Передавай эти поля.
Ответ 201 означает, что заказ подтверждён и будет передан в фулфилмент — тебе больше ничего не нужно делать, чтобы набор упаковали и отправили. Требуется право доступа home_kit_orders_manage. Передай необязательный заголовок Idempotency-Key, чтобы этот запрос на создание можно было безопасно повторять — повтор с тем же ключом вернёт исходный ответ вместо создания второй записи. См. Идемпотентность.

Запрос

Параметры тела запроса

string
обязательно
UUID профиля пациента, для которого создаётся заказ набора для домашнего теста.
string
обязательно
UUID панели из каталога для заказа. Ровно одна — набор для домашнего теста соответствует физическому набору 1:1, поэтому панель и есть набор. ID панелей Aniva предоставляет для твоего партнёрского аккаунта; см. Список панелей. Необязательно для замены — в этом случае по умолчанию используется панель заменяемого заказа.
string
UUID заказа набора для домашнего теста, который заменяет этот заказ. Передача этого поля делает заказ набором на замену — см. Наборы на замену выше. Заказ должен принадлежать тому же профилю, и для него ещё не должно быть замены в пути.
string
Причина замены в одном предложении (например, Zu wenig Material, HbA1c nicht auswertbar). Обязательно при передаче replaces_home_kit_order_id, в остальных случаях игнорируется. Максимум 500 символов.
integer[]
Для замены — маркеры, которые лаборатория повторит; обычно это те, по которым первый набор не смог дать результат. Каждый из них должен входить в состав заменяемого заказа; сверь со Списком биомаркеров с параметром home_kit=true. Не передавай это поле, чтобы повторить всю панель. Принимается только вместе с replaces_home_kit_order_id и не принимается вместе с другим panel_id. Дополнительный scope не нужен: повтор маркеров, за которые пациент уже заплатил, не считается отдельным выбором.
object
Твои собственные пары ключ/значение — возвращаются без изменений при каждом чтении и никогда не интерпретируются Aniva. Используй это поле для передачи своего идентификатора заказа, чтобы сопоставлять заказы без хранения наших ID. Максимум 20 ключей; ключи соответствуют [A-Za-z0-9_-] и содержат не более 40 символов; значения — строка, число или логическое значение (строки не длиннее 500 символов); общий размер в сериализованном виде — до 16 384 байт. Ключи, начинающиеся с aniva_, зарезервированы. Никогда не помещай персональные или клинические данные в metadata — это поле не обрабатывается как данные пациента.
string[]
До 5 адресов, на каждый из которых придёт одно письмо, когда все лабораторные результаты станут окончательными. В письме есть ссылка на страницу результатов в админ-панели Aniva. Твоему ключу нужен доступ results_view к пациенту, иначе вернётся 403. Не передавай поле, чтобы использовать адреса по умолчанию для группы пациента. Пустой список отключает отправку писем. См. Письма о готовности результатов.
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 не поддерживается.

Ответ

При успехе API возвращает 201 Created с новым заказом набора для домашнего теста.
string
обязательно
Уникальный идентификатор заказа набора для домашнего теста (UUID).
string
обязательно
UUID профиля, которому принадлежит этот заказ набора для домашнего теста.
string
обязательно
Текущий статус заказа набора для домашнего теста. Одно из значений: pending, dispatched, activated или cancelled. Только что созданный заказ получает статус pending.
object
обязательно
Адрес доставки набора — один из двух форматов: либо { location_id } со ссылкой на известную локацию тестирования, либо поля встроенного адреса (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email необязательны — те же поля, что и в API локаций). Укажи ровно один вариант — ссылку на локацию или встроенный адрес, но не оба сразу.
object
обязательно
Переданные тобой пары ключ/значение. Поле всегда присутствует — {}, если ничего не передано.
string
Заказ набора для домашнего теста, который заменяет этот заказ. null для обычного заказа.
string
Указанная тобой причина. null для обычного заказа.
string[]
обязательно
Адреса в нижнем регистре, на каждый из которых приходит одно письмо, когда все результаты лаборатории готовы. Пустой список, если отключено. См. Письма о готовности результатов.
string
Лабораторный код образца, под которым приходят результаты — напечатан на физическом наборе, его пациент считывает с коробки как код активации. null, пока набор не упакован. Только для чтения.
string
обязательно
Время сбора образца, переданное через Активацию. null, пока набор не активирован.
string
обязательно
Метка времени создания заказа набора для домашнего теста в формате ISO 8601.
string
Временная метка последнего обновления в формате ISO 8601. Может быть null.
object
обязательно
Профиль пациента, связанный с этим заказом набора для домашнего теста.
HomeKitOrderPanel[]
обязательно
Панель, привязанная к этому заказу набора для домашнего теста — та, что передана в panel_id, с меткой времени создания заказа. Всегда ровно одна. Подробности о панели (название, биомаркеры) смотри в Списке панелей.
HomeKitOrderIndividualBiomarker[]
обязательно
Биомаркеры, добавленные вне панели. При обычном создании список пуст — наборы для домашнего теста заказываются по панелям, а для последующего изменения этого списка требуется scope возможностей home_kit_orders_individual_biomarker_selection. При замене здесь находятся переданные тобой biomarker_ids — именно их лаборатория повторит.
HomeKitOrderShipmentLink[]
обязательно
Посылки, связанные с этим заказом набора для домашнего теста, от самой ранней привязки к более поздним. При создании список всегда пуст — полные данные по посылкам получай через Список отправлений с параметром ?home_kit_order_id=.

Ответы с ошибками