> ## 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.

# Список відправлень

> Отримати відправлення, відфільтровані за записом, замовленням домашнього набору або статусом

Отримай відправлення, доступні твоєму API-ключу, спочатку найновіші. У цьому єдиному списку зібрані всі посилки:
кур’єрський забір із практики, набір для домашнього тесту на шляху до пацієнта та зразок на
шляху назад. Відфільтруй за одним батьківським об’єктом за допомогою `appointment_id` або `home_kit_order_id`.

Потребує області доступу `shipments_view` або `shipments_manage`.

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

## Запит

### Параметри запиту

**appointment\_id** `string`

Лише відправлення, пов’язані з цим записом (UUID). `404`, якщо запис не існує, `403`,
якщо він поза твоїм контекстом доступу.

**home\_kit\_order\_id** `string`

Лише відправлення, пов’язані з цим замовленням набору для домашнього тесту (UUID). Зазвичай повертаються два рядки — набір на
шляху до пацієнта та зразок назад до лабораторії (його `destination` — лабораторія). Ті самі
правила `404` / `403`, що й для `appointment_id`.

**status** `string`

Лише відправлення у цьому статусі. Одне зі значень: `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Максимальна кількість відправлень у відповіді. За замовчуванням 100, максимум 500.

**offset** `integer`

Кількість відправлень, яку потрібно пропустити. За замовчуванням 0. Сортування стабільне (`created_at` за спаданням, потім
за номером), тож сторінки не перетинаються.

## Відповідь

У разі успіху API повертає `200 OK` із масивом об’єктів відправлень.

**id** `string` *required*

Ідентифікатор відправлення.

**status** `string` *required*

Статус життєвого циклу відправлення. Одне зі значень: `pending`, `in_transit`, `delivered`,
`fault` або `cancelled`.

**logistics\_provider** `string` *required*

Логістичний провайдер. Одне зі значень: `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` або `dhl_express`. Для посилки з домашнім набором це `dhl_parcel`, або `dhl_warenpost`, якщо вона прямує за кордон
як Warenpost International.

**tracking\_number** `string`

Зовнішній трек-номер від логістичного провайдера. Може бути `null`.

**contents** `string`

Довільний текстовий опис вмісту посилки, вказаний під час створення (наприклад, `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Лише для інформації — чи прямує посилка до
лабораторії, визначається за `destination`, а її парне відправлення — за `paired_with`. Може бути
`null`.

**booked\_by** `string` *required*

Хто надрукував етикетку: `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** `string`

Номер іншої посилки у відправленні з двох посилок — тієї, що доставила зворотну
етикетку, і тієї, яку ця етикетка повертає назад. Заповнено в обох. `null` для односторонньої посилки.

**origin** `object`

Адреса забору відправлення. Може бути `null`.

**об’єкт адреси**

**name** `string` *required*

Ім’я отримувача, назва компанії або локації.

**company\_name** `string`

Рядок компанії або c/o. Може бути `null`.

**street** `string` *required*

Назва вулиці без номера будинку.

**house\_number** `string`

Номер будинку. Може бути `null`.

**address\_line\_2** `string`

Корпус, під’їзд або поверх. Може бути `null`.

**city** `string` *required*

Місто.

**state** `string`

Штат або провінція. Може бути `null`.

**postal\_code** `string` *required*

Поштовий індекс.

**country\_code** `string` *required*

Код країни у форматі ISO 3166-1 alpha-2.

**phone** `string`

Контактний номер телефону. Може бути `null`.

**email** `string`

Контактна електронна пошта. Може бути `null`.

**destination** `object`

Адреса доставки. Така сама структура, як в `origin`. Може бути `null`.

**pickup** `object`

Заплановане вікно забору. Може бути `null`.

**об’єкт pickup**

**from** `string` *required*

Початок вікна забору як момент часу UTC (ISO 8601 із суфіксом `Z`).

**till** `string` *required*

Кінець вікна забору як момент часу UTC (ISO 8601 із суфіксом `Z`).

**timezone** `string` *required*

Часовий пояс IANA локації забору (наприклад, `Europe/Berlin`). Використовуй для відображення `from` / `till` за місцевим часом локації забору.

**notes** `string`

Необов’язкові примітки. Може бути `null`.

**status\_updates** `object[]` *required*

Хронологічні події життєвого циклу від логістичного провайдера (спочатку найстаріші). Порожній масив, якщо
провайдер ще не передав жодної події. Використовуй це поле для відображення окремих подій в інтерфейсі, аудиту й детальніших
сигналів перевізника; для канонічного поточного стану орієнтуйся на `status`.

**поля оновлення статусу**

**state** `string | null` *required*

Подія у словнику статусів відправлення — `pending`, `in_transit`, `delivered` або
`fault` — щоб можна було читати хронологію без знання кодів перевізника. `null`, коли
подія не містить стану (створення етикетки, сканування перевізника без інформації, події, зафіксовані
до появи цього поля). Ніколи не буває `cancelled`.

**code** `string | null` *required*

Власний код статусу перевізника: у GO! це `GO10` / `GO90` / `GOY001`, у DHL — `VA` / `ZF` / `LA`
/ `ZU`. `null`, якщо перевізник його не передав. Не змінюється залежно від мови перекладу
`status`.

**detail\_code** `string | null` *required*

Детальніший код перевізника, якщо він є — поле `statusDetailed` у DHL, наприклад `CNRFC_NRQRD_ZF`
(перенаправлено до поштового відділення), `HLDCC_SERPT_LA` (готово до видачі там), `DLVRD_SERPT_ZU`
(отримано). `null` для перевізників без такого коду.

**status** `string` *required*

Текст статусу від провайдера (довільний текст, наприклад `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Пояснення коду або розгорнутіший опис від перевізника. `null`, якщо немає жодного з них.

**location** `string | null` *required*

Місце сканування так, як його називає перевізник — депо GO! (`"HUB Niederaula"`) або
місто DHL. Довільний текст, не координати. `null`, якщо перевізник не передав місце.

**time** `string` *required*

Час фіксації події (ISO 8601, зі зміщенням часового поясу, яке передав перевізник).

**appointments** `ShipmentAppointmentLink[]` *required*

Записи, пов’язані з цим відправленням, спочатку найраніше додані. Кожен елемент має вигляд `{ id, added_at }`;
використай кожен `id` в [Отримати запис](https://docs.anivahealth.com/uk/api/appointments/get-appointment.md), щоб отримати
повні дані запису. Порожній масив, якщо пов’язаних записів немає.
У списку лише ті записи, що входять у твій контекст доступу.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Замовлення наборів для домашнього тесту, пов’язані з цим відправленням, спочатку найраніше додані, у тій самій формі `{ id, added_at }`.
Використай кожен `id` в [Отримати замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/get-home-kit.md). Порожній
масив для посилок із практик. У списку лише замовлення у твоєму контексті доступу. Див.
[Доступ](https://docs.anivahealth.com/uk/concepts/shipments.md#dostup).

**synced\_at** `string`

Коли відправлення востаннє звірялося з перевізником, у форматі часу UTC. Запити на читання ніколи не звертаються до
перевізника — дані оновлює фонова синхронізація — тож це поле показує, наскільки свіжою є відповідь. `null` до
першої синхронізації.

**created\_at** `string` *required*

Часова мітка створення (ISO 8601).

**updated\_at** `string`

Часова мітка останнього оновлення (ISO 8601). Може бути `null`.

## Повторні виклики

Aniva зберігає відповідь цього ендпойнта 5 хвилин для кожного API-ключа. Повторний виклик упродовж
цього часу отримує збережену відповідь. Заголовки `Cache-Status` і `Age` показують, що відповідь
збережена і як давно її збережено.

Щоб дізнаватися про зміни одразу, підпишись на вебхук-події `shipment.created` і `shipment.updated`.
Див. [Повторні читання](https://docs.anivahealth.com/uk/concepts/webhooks.md#povtorni-chitannya).

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

| Статус | Опис |
| - | - |
| `400` | Неправильний параметр запиту. |
| `403` | Доступ заборонено — бракує дозволу або відфільтрований запис / замовлення набору для домашнього тесту перебуває поза твоєю областю доступу. |
| `404` | Відфільтрований запис або замовлення набору для домашнього тесту не знайдено. |
| `500` | Внутрішня помилка сервера. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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