> ## 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 Aniva: отправка образцов в лабораторию и посылки с наборами для домашнего теста с отслеживанием и статусом.

Отправление — это одна физическая посылка: курьерский забор с образцами крови из пункта сдачи в лабораторию, набор для домашнего теста на пути к пациенту или образец, который этот пациент отправляет обратно почтой. Shipments API позволяет создавать, отслеживать, изменять и отменять заказы на доставку и показывает все посылки в одном месте, независимо от того, кто их оформил.

## Один список с фильтрацией

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

## Содержимое и кто оформил доставку

В каждом отправлении указаны два факта, которые не видны по его адресам:

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

Посылка с обратной этикеткой и посылка, которая возвращается по этой этикетке, ссылаются друг на друга через `paired_with`.

## Доступ

* Ты можешь просматривать посылку, если хотя бы одна связанная запись или заказ набора для домашнего теста находится в твоём контексте доступа, либо если она отправлена из локации в твоём контексте доступа.
* `appointments` и `home_kit_orders` содержат только записи и заказы из твоего контекста доступа.
* Для [Обновить](https://docs.anivahealth.com/ru/api/shipments/update-shipment.md), [Отменить](https://docs.anivahealth.com/ru/api/shipments/cancel-shipment.md), [Привязать записи](https://docs.anivahealth.com/ru/api/shipments/attach-appointments-to-shipment.md) и [Отвязать записи](https://docs.anivahealth.com/ru/api/shipments/detach-appointments-from-shipment.md) нужно, чтобы все связанные заказы наборов для домашнего теста входили в твой контекст доступа. Иначе вызов вернёт `403`, и изменить посылку сможет только Aniva.

## Чтение никогда не обращается к перевозчику

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

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

При создании отправления ты указываешь исходный `location_id` — пункт сдачи, откуда курьер должен забрать посылку. Также ты указываешь целевую лабораторию в `destination_lab`. Отправление поедет на зарегистрированный адрес доставки этой лаборатории.

Локация должна входить в контекст доступа твоего API-ключа. Используй [Список локаций](https://docs.anivahealth.com/ru/api/locations/list-locations.md), чтобы найти доступные идентификаторы локаций.

При желании ты можешь передать `appointment_id`, чтобы привязать отправление к конкретной записи
при создании. Связь отображается напрямую с обеих сторон:

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

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

Отправление может быть связано с несколькими записями, а запись — с несколькими
отправлениями. После создания управляй связями с помощью [Привязать записи к
отправлению](https://docs.anivahealth.com/ru/api/shipments/attach-appointments-to-shipment.md) /
[Отвязать записи от отправления](https://docs.anivahealth.com/ru/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/ru/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-raspisaniya-zabora).

> [!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/ru/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.