> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Відправлення

> Як працює логістика в Aniva API: відправлення зразків до лабораторії та посилки з наборами для домашнього тесту, із відстеженням і статусом.

Відправлення — це одна фізична посилка: кур’єрський забір зі зразками крові з пункту тестування до лабораторії, набір для домашнього тесту на шляху до пацієнта або зразок, який пацієнт надсилає поштою назад. API відправлень дозволяє створювати, відстежувати, змінювати та скасовувати замовлення на відправлення, а також показує всі посилки в одному списку незалежно від того, хто їх оформив.

## Один список із фільтрацією

`GET /api/v1/shipments` — єдина колекція. Відправлення є самостійною сутністю — воно має зв’язок багато до багатьох із записами та може належати до замовлення набору для домашнього тесту — тому вкладеного списку всередині батьківського об’єкта немає. Звужуй цей самий список за допомогою `?appointment_id=` або `?home_kit_order_id=`, переглядай сторінки через `limit` / `offset` і переходь із вбудованого масиву `shipments` батьківського об’єкта (`{ id, added_at }` як у записах, так і в замовленнях наборів для домашнього тесту) до [Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md), коли маєш конкретний id.

## Вміст і хто оформив відправлення

Кожне відправлення містить два факти, яких не видно з його адрес:

* `contents` — довільний текст з описом вмісту посилки, що задається під час створення (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) і показується кур’єру. Має лише інформаційний характер. Напрямок не є окремим полем: чи прямує посилка до лабораторії, визначається за `destination`.
* `booked_by` — хто надрукував етикетку: `aniva` або `external`. Лише відправлення `aniva` підтримують [Оновити](https://docs.anivahealth.com/uk/api/shipments/update-shipment.md) і [Скасувати](https://docs.anivahealth.com/uk/api/shipments/cancel-shipment.md); посилка `external` відстежується в тому самому списку, але повертає `501` на обидва запити.

Посилка, яка містила етикетку для повернення, та посилка, що повертається за цією етикеткою, посилаються одна на одну через `paired_with`.

## Доступ

* Ти можеш переглядати посилку, якщо принаймні один пов’язаний запис або замовлення набору для домашнього тесту входить у твій контекст доступу, або якщо її відправлено з локації у твоєму контексті доступу.
* `appointments` і `home_kit_orders` містять лише записи та замовлення з твого контексту доступу.
* [Оновити](https://docs.anivahealth.com/uk/api/shipments/update-shipment.md), [Скасувати](https://docs.anivahealth.com/uk/api/shipments/cancel-shipment.md), [Прив’язати записи](https://docs.anivahealth.com/uk/api/shipments/attach-appointments-to-shipment.md) і [Відв’язати записи](https://docs.anivahealth.com/uk/api/shipments/detach-appointments-from-shipment.md) вимагають, щоб кожне пов’язане замовлення набору для домашнього тесту входило у твій контекст доступу. Інакше виклик повертає `403`, і змінити посилку може лише Aniva.

## Читання ніколи не звертається до перевізника

Кожне читання обслуговується з нашої бази даних. Фонова синхронізація звіряє кожне відправлення з перевізником (кожні 10 хвилин для GO!, щогодини для DHL) і проставляє `synced_at`, що показує актуальність будь-якої відповіді. Примусового оновлення немає — DHL дозволяє один запит відстеження раз на п’ять секунд, тому читання із запитом безпосередньо до перевізника неможливе.

## Створення відправлення

Під час створення відправлення ти вказуєш початкову локацію `location_id` — пункт тестування, звідки кур’єр має забрати посилку. Також ти вказуєш лабораторію призначення через `destination_lab`. Відправлення прямує на зареєстровану поштову адресу цієї лабораторії.

Локація має входити в контекст доступу твого ключа API. Використай [Отримати список локацій](https://docs.anivahealth.com/uk/api/locations/list-locations.md), щоб знайти доступні ID локацій.

За бажанням ти можеш передати `appointment_id`, щоб прив’язати відправлення до конкретного запису під час
створення. Зв’язок відображається вбудовано з обох боків:

* у відправленні — як масив `appointments` з елементів `{ id, added_at }`;
* у записі — як масив `shipments` з елементів `{ id, added_at }`.

Обидва масиви відсортовані від найдавнішого зв’язку. Кожен `id` посилається на канонічний ендпоінт деталей
([Отримати запис](https://docs.anivahealth.com/uk/api/appointments/get-appointment.md) /
[Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md)) для отримання повного набору даних — партнери, яким потрібен
статус кур’єрської доставки за кожним записом, переходять за кожним елементом у масиві `shipments` запису до
ендпоінту деталей відправлення.

Одне відправлення можна прив’язати до кількох записів, а один запис — до кількох
відправлень. Після створення керуй зв’язками через [Прив’язати записи до
відправлення](https://docs.anivahealth.com/uk/api/shipments/attach-appointments-to-shipment.md) /
[Відв’язати записи від відправлення](https://docs.anivahealth.com/uk/api/shipments/detach-appointments-from-shipment.md). Кожна
зміна повертає оновлений список записів відправлення.

Правило змін таке: зв’язки можна створювати або видаляти, коли АБО запис уже після
забору крові (`blood_drawn`), або відправлення створено менш ніж 24 години тому. Поза цим
вікном зв’язок блокується, щоб історичні дані залишалися стабільними.

## Життєвий цикл

Відправлення проходять через такі статуси:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Статус | Значення |
| - | - |
| `pending` | Замовлення кур’єра оформлено, воно очікує на забір. |
| `in_transit` | Кур’єр забрав посилку, вона в дорозі. |
| `delivered` | Посилку доставлено. |
| `fault` | Під час доставки виникла проблема або перевізник повернув посилку відправнику. |
| `cancelled` | Відправлення скасовано. |

Кожна зміна статусу надсилає [вебхук](https://docs.anivahealth.com/uk/concepts/webhooks.md) `shipment.*`, наприклад
`shipment.delivered`. `shipment.updated` спрацьовує під час кожної зміни, яку ти можеш прочитати, наприклад нового сканування.

## Правила графіка забору

Ці правила діють під час створення або оновлення графіка забору відправлення. `pickup_date`
(`YYYY-MM-DD`) і `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24-годинний формат) — це значення локального часу,
**які інтерпретуються в часовому поясі IANA точки відправлення** — ти не надсилаєш часовий пояс разом із ними.

| Правило | Деталі |
| - | - |
| **Лише будні** | `pickup_date` має припадати на понеділок–п’ятницю. |
| **Сьогодні або пізніше** | `pickup_date` не може бути в минулому. |
| **Кінцевий час на сьогодні** | Замовлення забору на той самий день відхиляються після 16:00 Europe/Berlin. |
| **Діапазон вікна** | `pickup_time_from` і `pickup_time_till` мають бути в межах 09:00–19:00. |
| **Мінімальне вікно 2 год** | Вікно забору має тривати щонайменше 2 години. |

## Зміна відправлень

Ти можеш оновити графік забору, кількість посилок, вагу та примітки відправлення за допомогою `PATCH /api/v1/shipments/{id}`. Якщо змінюється будь-яке важливе для логістики поле (дата забору, час, кількість посилок або вага), наявне логістичне замовлення автоматично скасовується і створюється нове. Поля, які ти пропустиш у тілі запиту, зберігаються з наявного відправлення — наприклад, якщо оновити лише `weight`, замовлення перествориться з тим самим графіком забору. Оновлені поля графіка перевіряються за тими самими [правилами графіка забору](#pravila-grafika-zaboru).

> [!WARNING]
>
> Відправлення не можна змінити після того, як кур’єр забрав посилку. Спроби оновити
> відправлення у статусі `in_transit`, `delivered` або `fault` повертають `409 Conflict`.

Якщо логістичний провайдер відхиляє скасування або повторне створення під час оновлення, API повертає `502 Bad Gateway` із повідомленням про помилку від провайдера.

## Скасування відправлень

Скасуй відправлення за допомогою `DELETE /api/v1/shipments/{id}`. Це викликає API логістичного провайдера для скасування замовлення й оновлює статус на `cancelled`.

> [!WARNING]
>
> Відправлення не можна скасувати після забору. Спроби скасувати відправлення, яке вже має
> статус `in_transit`, `delivered` або `fault`, повертають `409 Conflict`. Скасування відправлення, яке вже
> у статусі `cancelled`, нічого не змінює і повертає `200` із цим відправленням — див.
> [Ідемпотентність](https://docs.anivahealth.com/uk/concepts/idempotency.md).

Логістичний провайдер також може відхилити скасування з власних причин (наприклад, минув кінцевий термін скасування). У такому разі API повертає `502 Bad Gateway` із повідомленням про помилку та кодом помилки від провайдера.

### Етикетки для повернення

Етикетка для повернення DHL є частиною вихідного замовлення. DHL не може скасувати етикетку окремо, тому скасування рядка, який відстежує етикетку для повернення, повертає `409 Conflict`. Натомість скасуй вихідну посилку, поки вона у статусі `pending`. Це скасує й етикетку: кожен рядок зворотного відправлення вихідної посилки у статусі `pending` перейде у статус `cancelled` і отримає запис `RETURN_LEG_CANCELLED` у своєму `status_updates`. Зворотна посилка, яку пацієнт уже надіслав, продовжує рух. Після відправлення вихідної посилки етикетка залишається дійсною, а Aniva закриває рядок зворотного відправлення вручну.

## Референсні ID відправлень

Кожне відправлення має референсний ID з 11 символів: літера, дата й чотири символи, `{letter}YYMMDDXXXX` (наприклад, `P2611194821`). Літера показує, до чого належить відправлення, і ніколи не вказує на його напрямок:

| Літера | Відправлення |
| - | - |
| `P` | Відправлення, яке ти створюєш через цей API. |
| `M` | Відправлення, яке створює команда Aniva. |
| `C` | Відправлення зі щоденної відправки Aniva. |
| `K` | Посилка з домашнім набором. |
| `F`, `S` | Власні складські посилки Aniva. |

Відправлення з 20 до 22 листопада 2026 року зберігає свій ID зі словом на початку: `API`, `MAN`, `AUTO` або `KIT` (наприклад, `AUTO261121UWKX`). Обидва формати залишаються дійсними. Не перевіряй довжину чи першу літеру ID. Використовуй ID, щоб отримати, оновити або скасувати відправлення.

## Адреси відправлень

Поля `origin` і `destination` у відповіді відправлення містять визначені об’єкти адрес із такою структурою:

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

Для посилки з практики адреса `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`
після сканування передачі), тому сам лише найновіший запис не показує реальний стан посилки.

## Приклад відправлення

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Приклад посилок із домашнім набором

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` повертає парою набір, що прямує до пацієнта, і зразок, що повертається назад:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

Рядок зворотного відправлення існує з моменту друку етикетки для повернення й залишається у статусі `pending`, доки пацієнт не надішле зразок — це фактичний стан, а не прогалина.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.