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

Поля

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. ID панелей надає Aniva для твого партнерського акаунта.
Панелі потрібно додати до забору крові — тобто поки запис має статус pending або confirmed. Ти не зможеш додати або змінити панелі після того, як запис перейде у статус blood_drawn.

Видалення панелей

Якщо тобі потрібно видалити панелі до забору крові, виклич:
Передай масив UUID панелей у полі panel_ids. Видалення ідемпотентне: неприкріплена панель ігнорується.
Як і додавання панелей, видалення дозволене лише до забору крові — тобто поки запис має статус pending або confirmed. Панелі не можна видалити після того, як запис перейшов у статус blood_drawn.

Окремі біомаркери

Ти можеш прикріпити окремі біомаркери до запису як аналізи на вибір, поза готовими панелями. Це зручно, коли фахівцю потрібен індивідуальний набір замість готового пакета. Прикріплені біомаркери з’являються у відповіді запису як масив individual_biomarkers (на одному рівні з panels). Рішення щодо маршрутизації ухвалюються далі в пайплайні логістики замовлень на основі відповідностей кожного біомаркера для окремих лабораторій. Додай біомаркери (ідемпотентно — уже прикріплені біомаркери зберігаються):
Видали біомаркери (ідемпотентно — неприкріплені біомаркери ігноруються):
Обидва ендпоінти приймають масив biomarker_ids і перевіряють підсумковий набір на відповідність правилам замикання кожної лабораторії — замовлення, яке неможливо коректно оформити (наприклад, співвідношення CRP/HDL без CRP і HDL), повертає 400 із біомаркерами, які потрібно додати, і нічого не зберігає. Використовуй Список біомаркерів, щоб знайти ID біомаркерів.
Як і зміни панелей, окремі біомаркери можна додавати або видаляти лише до забору крові — тобто поки запис має статус 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, оскільки шлях потрапляє на маршрут запису за ID. На останньому етапі цей ендпоінт працював як заглушка, що приймала виклик і нічого не робила, тож його видалення не змінює жодної поведінки, на яку ти покладаєшся.
Щоб відстежувати перебіг після забору крові, перейди за кожним елементом із вбудованого масиву 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 повідомить тебе, коли це станеться, тож опитування не потрібне. Масив submissions розбиває ці дані за кожним лабораторним направленням із власним lab_code. Кожен отриманий результат і документ містить lab_code, під яким його подано. Посилання на PDF-файли лабораторних звітів містяться в масиві documents — використовуй GET /api/v1/documents/{id}, щоб завантажити їх.

Приклад запису