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

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

> Створити логістичне замовлення на відправлення з указаними початковим пунктом і пунктом призначення

Створи замовлення на відправлення з указаної початкової локації. Лабораторію призначення ти вказуєш через `destination_lab`. Відправлення надсилається на зареєстровану адресу доставки цієї лабораторії.

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

Надішли необов’язковий заголовок `Idempotency-Key`, щоб зробити повторний запит на створення безпечним — повторення з тим самим ключем повертає початкову відповідь замість створення другого запису. Див. [Ідемпотентність](https://docs.anivahealth.com/uk/concepts/idempotency.md).

## Запит

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

**location\_id** `string` *required*

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

**destination\_lab** `string` *required*

Лабораторія призначення. Одне зі значень: `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`,
`imd` або `quade`. Відправлення надсилається на адресу доставки, зареєстровану для цієї
лабораторії. Для лабораторії без зареєстрованої адреси доставки повертається `400`.

**appointment\_id** `string`

Необов’язковий UUID запису, до якого потрібно прив’язати це відправлення під час створення.
Запис має бути в межах контексту доступу твого API-ключа. Зв’язок відображається як елемент у
масиві `appointments` відправлення і навпаки — як елемент у масиві `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).

**pickup\_date** `string` *required*

Дата забору у форматі `YYYY-MM-DD` (наприклад, `2026-04-15`), що інтерпретується в часовому
поясі початкової локації. Має бути будній день (понеділок–п’ятниця), сьогодні або в майбутньому.
Забір у той самий день недоступний після 16:00 Europe/Berlin.

**pickup\_time\_from** `string` *required*

Найраніший час забору у форматі `HH:MM` (наприклад, `09:00`), що інтерпретується як місцевий
час у часовому поясі початкової локації. Має бути між `09:00` і `19:00`.

**pickup\_time\_till** `string` *required*

Найпізніший час забору у форматі `HH:MM` (наприклад, `12:00`), що інтерпретується як місцевий
час у часовому поясі початкової локації. Має бути між `09:00` і `19:00`. Вікно
(`pickup_time_till - pickup_time_from`) має тривати щонайменше 2 години.

**package\_count** `integer` (default: 1)

Кількість пакунків. За замовчуванням `1`.

**weight** `number` (default: 0.5)

Вага в kg. За замовчуванням `0.5`.

**pickup\_remarks** `string`

Інструкції для кур’єра під час забору (примітки відправника). Якщо не вказано, використовуються
збережені примітки адреси забору (або жодних, якщо для адреси їх немає). Максимум 128 символів.

**contents** `string`

Довільний текстовий опис вмісту посилки, який показується кур’єру та повертається в полі
`contents`. Максимум 40 символів (наприклад, `Medizinisch freigestellte Probe`).

**notes** `string`

Необов’язкові внутрішні примітки. Максимум 128 символів.

## Відповідь

У разі успіху API повертає `201 Created` із новим відправленням.

**id** `string` *required*

Референсний ідентифікатор відправлення (наприклад, `P2604151234`).

**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`

Опис вмісту посилки в довільній формі, вказаний під час створення. Може бути `null`.

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

Хто надрукував етикетку: `aniva` або `external`. Відправлення, яке ти створюєш, має значення
`aniva`.

**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*

Хронологічні події життєвого циклу від логістичного провайдера (спочатку найстаріші). Кожен
елемент містить `state`, `code`, `detail_code`, `status`, `description`, `location` і `time`.
Опис кожного поля дивись в [Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md). Порожній масив
одразу після створення. Фонова синхронізація додає події в міру того, як їх повідомляє провайдер.

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

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

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

Замовлення домашніх наборів, прив’язані до цього відправлення, у тому ж форматі `{ id, added_at }`.
Порожній масив для відправлення, яке ти створюєш.

**synced\_at** `string`

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

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

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

**updated\_at** `string`

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

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

| Статус | Опис |
| - | - |
| `400` | Помилка валідації — наприклад, некоректний формат дати, вихідний день, занадто коротке вікно забору, минув крайній час для забору в той самий день. Також повертається, якщо в `destination_lab` або початкової локації немає зареєстрованої адреси. |
| `403` | Заборонено — твій API-ключ не має доступу до цієї операції або локація поза твоїм контекстом доступу. |
| `404` | Локацію не знайдено або вона неактивна, або передано `appointment_id`, але такого запису не існує. |
| `409` | Ключ `Idempotency-Key` уже використано з іншим тілом запиту або початковий запит із ним ще не завершився. |
| `500` | Внутрішня помилка сервера. |
| `502` | Логістичний провайдер відхилив запит. Містить повідомлення про помилку від провайдера. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 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-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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