> ## 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/ru/api/shipments/update-shipment.md) и [Отмена](https://docs.anivahealth.com/ru/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`

Контактный email. Может быть `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*

Более детальный код перевозчика, если он есть — у DHL это `statusDetailed`, например
`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/ru/api/appointments/get-appointment.md),
чтобы получить полные данные записи. Пустой массив, если записи не привязаны.
Перечислены только записи в твоем контексте доступа.

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

Заказы наборов для домашнего теста, привязанные к этому отправлению, начиная с самой ранней
привязки, в том же формате `{ id, added_at }`. Сверь каждый `id` через
[Получение заказа набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/get-home-kit.md). Пустой массив
для посылок из практик. Перечислены только заказы в твоем контексте доступа. См.
[Доступ](https://docs.anivahealth.com/ru/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/ru/concepts/webhooks.md#povtornye-chteniya).

## Ответы с ошибками

| Статус | Описание |
| - | - |
| `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.