Один список із фільтрацією
GET /api/v1/shipments — єдина колекція. Відправлення є самостійною сутністю — воно має зв’язок багато до багатьох із записами та може належати до замовлення набору для домашнього тесту — тому вкладеного списку всередині батьківського об’єкта немає. Звужуй цей самий список за допомогою ?appointment_id= або ?home_kit_order_id=, переглядай сторінки через limit / offset і переходь із вбудованого масиву shipments батьківського об’єкта ({ id, added_at } як у записах, так і в замовленнях наборів для домашнього тесту) до Отримати відправлення, коли маєш конкретний id.
Вміст і хто оформив відправлення
Кожне відправлення містить два факти, яких не видно з його адрес:contents— довільний текст з описом вмісту посилки, що задається під час створення ("Medizinisch freigestellte Probe","Home test kit") і показується кур’єру. Має лише інформаційний характер. Напрямок не є окремим полем: чи прямує посилка до лабораторії, визначається заdestination.booked_by— хто надрукував етикетку:anivaабоexternal. Лише відправленняanivaпідтримують Оновити і Скасувати; посилкаexternalвідстежується в тому самому списку, але повертає501на обидва запити.
paired_with.
Доступ
- Ти можеш переглядати посилку, якщо принаймні один пов’язаний запис або замовлення набору для домашнього тесту входить у твій контекст доступу, або якщо її відправлено з локації у твоєму контексті доступу.
appointmentsіhome_kit_ordersмістять лише записи та замовлення з твого контексту доступу.- Оновити, Скасувати, Прив’язати записи і Відв’язати записи вимагають, щоб кожне пов’язане замовлення набору для домашнього тесту входило у твій контекст доступу. Інакше виклик повертає
403, і змінити посилку може лише Aniva.
Читання ніколи не звертається до перевізника
Кожне читання обслуговується з нашої бази даних. Фонова синхронізація звіряє кожне відправлення з перевізником (кожні 10 хвилин для GO!, щогодини для DHL) і проставляєsynced_at, що показує актуальність будь-якої відповіді. Примусового оновлення немає — DHL дозволяє один запит відстеження раз на п’ять секунд, тому читання із запитом безпосередньо до перевізника неможливе.
Створення відправлення
Під час створення відправлення ти вказуєш початкову локаціюlocation_id — пункт тестування, звідки кур’єр має забрати посилку. Також ти вказуєш лабораторію призначення через destination_lab. Відправлення прямує на зареєстровану поштову адресу цієї лабораторії.
Локація має входити в контекст доступу твого ключа API. Використай Отримати список локацій, щоб знайти доступні ID локацій.
За бажанням ти можеш передати appointment_id, щоб прив’язати відправлення до конкретного запису під час
створення. Зв’язок відображається вбудовано з обох боків:
- у відправленні — як масив
appointmentsз елементів{ id, added_at }; - у записі — як масив
shipmentsз елементів{ id, added_at }.
id посилається на канонічний ендпоінт деталей
(Отримати запис /
Отримати відправлення) для отримання повного набору даних — партнери, яким потрібен
статус кур’єрської доставки за кожним записом, переходять за кожним елементом у масиві shipments запису до
ендпоінту деталей відправлення.
Одне відправлення можна прив’язати до кількох записів, а один запис — до кількох
відправлень. Після створення керуй зв’язками через Прив’язати записи до
відправлення /
Відв’язати записи від відправлення. Кожна
зміна повертає оновлений список записів відправлення.
Правило змін таке: зв’язки можна створювати або видаляти, коли АБО запис уже після
забору крові (blood_drawn), або відправлення створено менш ніж 24 години тому. Поза цим
вікном зв’язок блокується, щоб історичні дані залишалися стабільними.
Життєвий цикл
Відправлення проходять через такі статуси:
Кожна зміна статусу надсилає вебхук
shipment.*, наприклад
shipment.delivered. shipment.updated спрацьовує під час кожної зміни, яку ти можеш прочитати, наприклад нового сканування.
Правила графіка забору
Ці правила діють під час створення або оновлення графіка забору відправлення.pickup_date
(YYYY-MM-DD) і pickup_time_from / pickup_time_till (HH:MM, 24-годинний формат) — це значення локального часу,
які інтерпретуються в часовому поясі IANA точки відправлення — ти не надсилаєш часовий пояс разом із ними.
Зміна відправлень
Ти можеш оновити графік забору, кількість посилок, вагу та примітки відправлення за допомогоюPATCH /api/v1/shipments/{id}. Якщо змінюється будь-яке важливе для логістики поле (дата забору, час, кількість посилок або вага), наявне логістичне замовлення автоматично скасовується і створюється нове. Поля, які ти пропустиш у тілі запиту, зберігаються з наявного відправлення — наприклад, якщо оновити лише weight, замовлення перествориться з тим самим графіком забору. Оновлені поля графіка перевіряються за тими самими правилами графіка забору.
Якщо логістичний провайдер відхиляє скасування або повторне створення під час оновлення, API повертає 502 Bad Gateway із повідомленням про помилку від провайдера.
Скасування відправлень
Скасуй відправлення за допомогоюDELETE /api/v1/shipments/{id}. Це викликає API логістичного провайдера для скасування замовлення й оновлює статус на cancelled.
Логістичний провайдер також може відхилити скасування з власних причин (наприклад, минув кінцевий термін скасування). У такому разі API повертає 502 Bad Gateway із повідомленням про помилку та кодом помилки від провайдера.
Етикетки для повернення
Етикетка для повернення DHL є частиною вихідного замовлення. DHL не може скасувати етикетку окремо, тому скасування рядка, який відстежує етикетку для повернення, повертає409 Conflict. Натомість скасуй вихідну посилку, поки вона у статусі pending. Це скасує й етикетку: кожен рядок зворотного відправлення вихідної посилки у статусі pending перейде у статус cancelled і отримає запис RETURN_LEG_CANCELLED у своєму status_updates. Зворотна посилка, яку пацієнт уже надіслав, продовжує рух. Після відправлення вихідної посилки етикетка залишається дійсною, а Aniva закриває рядок зворотного відправлення вручну.
Референсні ID відправлень
Кожне відправлення має референсний ID з 11 символів: літера, дата й чотири символи,{letter}YYMMDDXXXX (наприклад, P2611194821). Літера показує, до чого належить відправлення, і ніколи не вказує на його напрямок:
Відправлення з 20 до 22 листопада 2026 року зберігає свій ID зі словом на початку:
API, MAN, AUTO або KIT (наприклад, AUTO261121UWKX). Обидва формати залишаються дійсними. Не перевіряй довжину чи першу літеру ID. Використовуй ID, щоб отримати, оновити або скасувати відправлення.
Адреси відправлень
Поляorigin і destination у відповіді відправлення містять визначені об’єкти адрес із такою структурою:
origin визначається за локацією тестування, вказаною під час
створення, а destination — це лабораторія, зазначена в destination_lab.
Для посилки з домашнім набором адреса доставки пацієнта є destination набору та
origin для повернення зразка; локація, де пакують набір, є його origin. Адреса
не містить location_id — зіставляй посилку з практики через запис, до якого вона
прив’язана.
Вікно забору
Полеpickup у відповіді відправлення містить заплановане вікно забору кур’єром. Воно
включає часові мітки from і till у форматі UTC (ISO 8601 із суфіксом Z, наприклад
2026-04-15T07:00:00Z) та рядок timezone (часовий пояс IANA локації забору). Локальні значення
pickup_date / pickup_time_*, передані під час створення або оновлення, перетворюються на ці
абсолютні часові точки за допомогою цього часового поясу — використовуй timezone, щоб знову відобразити from / till за
локальним часом місця забору. Поле має значення null, якщо вікно забору не заплановано.
Журнал оновлень статусу
Кожне відправлення містить масивstatus_updates — усі події життєвого циклу, про які повідомив
логістичний провайдер, починаючи з найдавнішої. Кожен запис містить:
state— подія в термінах статусів відправлення (pending,in_transit,delivered,fault), тож хронологію можна читати без знання кодів перевізника.null, коли подія не має статусу (створення етикетки, сканування перевізника без інформації, записи, створені до появи цього поля). Ніколи не буваєcancelled— скасування виконуємо ми, це не подія перевізника.code— власний код статусу перевізника (GO10,GO90,GOY001у GO!;VA,ZF,LA,ZUу DHL).null, якщо перевізник його не передав. Не залежить від мови перекладуstatus.detail_code— точніший код перевізника, якщо він є:statusDetailedу DHL, наприкладCNRFC_NRQRD_ZF(перенаправлено до поштового відділення),HLDCC_SERPT_LA(готово до видачі там),DLVRD_SERPT_ZU(забрано). В інших випадкахnull.status— зрозумілий людині підпис від перевізника (наприклад,"Shipment picked up","Die Sendung wurde abgeholt.").description— пояснення коду або довший опис від перевізника.null, якщо немає ні того, ні іншого.location— місце сканування в тому вигляді, як його називає перевізник: депо GO!, місто DHL. Довільний текст, не координати.time— часова мітка події в ISO 8601, як її передав перевізник (зі зміщенням часового поясу).
code
RETURNED_TO_SENDER. У його status міститься причина від перевізника. Після цього відправлення залишається у статусі fault, навіть
коли перевізник доставить посилку назад до нас.
Список може бути порожнім, якщо перевізник ще не повідомив про жодну подію.
Використовуй поле status верхнього рівня для канонічного поточного стану. Воно рухається в один бік — від pending
до in_transit і delivered — із накладанням fault, доки найновіша подія повідомляє про збій;
перевізники не впорядковують події за важливістю (DHL додає повідомлення про перенаправлення з кодом pre-transit
після сканування передачі), тому сам лише найновіший запис не показує реальний стан посилки.
Приклад відправлення
Приклад посилок із домашнім набором
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… повертає парою набір, що прямує до пацієнта, і зразок, що повертається назад:
pending, доки пацієнт не надішле зразок — це фактичний стан, а не прогалина.