Перейти до основного вмісту
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, тож панель і є цим набором. Ідентифікатори панелей надає 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. Для цього не потрібен додатковий дозвіл: повторне дослідження маркерів, які пацієнт уже оплатив, не є індивідуальним вибором.
object
Твої власні пари ключ/значення, які повертаються без змін під час кожного читання й ніколи не інтерпретуються Aniva. Використовуй це поле для зберігання власного номера замовлення, щоб зіставляти дані без збереження наших ідентифікаторів. Щонайбільше 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[]
обов'язково
Біомаркери, додані поза панеллю. Порожній список під час звичайного створення — набори для домашнього тесту замовляються за панелями, а подальше редагування цього списку потребує дозволу home_kit_orders_individual_biomarker_selection. У разі заміни містить передані тобою biomarker_ids, які лабораторія виконує повторно.
HomeKitOrderShipmentLink[]
обов'язково
Посилки, пов’язані з цим замовленням набору для домашнього тесту, від найстарішої прив’язки до найновішої. Завжди порожній список під час створення — отримуй повні дані про посилки через Список відправлень із параметром ?home_kit_order_id=.

Відповіді з помилками