Перейти до основного вмісту
За замовленням набору для домашнього тесту пацієнту надсилають поштовий набір для самостійного тестування. 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 (лише Німеччина): вкажи Packstation або Postfiliale у полі street, тризначний номер станції у house_number, а DHL Postnummer отримувача (6–10 цифр, допускаються пробіли) — у address_line_2. Без 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 повідомить тобі, коли це станеться, тож робити періодичні запити не потрібно. Посилання на PDF-звіти лабораторії містяться в масиві documents — використовуй GET /api/v1/documents/{id}, щоб їх завантажити.

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