Один список с фильтрацией
GET /api/v1/shipments — единственная коллекция. Отправление существует самостоятельно — оно связано с записями отношением многие ко многим и может относиться к заказу набора для домашнего теста — поэтому вложенного списка у родительского объекта нет. Фильтруй этот же список параметрами ?appointment_id= или ?home_kit_order_id=, разбивай на страницы с помощью limit / offset и переходи по встроенному массиву shipments родительского объекта ({ id, added_at } и у записей, и у заказов наборов для домашнего теста) к Получить отправление, если у тебя есть один идентификатор.
Содержимое и кто оформил доставку
В каждом отправлении указаны два факта, которые не видны по его адресам:contents— произвольный текст с описанием содержимого посылки, задаётся при создании ("Medizinisch freigestellte Probe","Home test kit") и показывается курьеру. Носит только информационный характер. Направление не хранится отдельным полем: движется ли посылка в лабораторию, определяется по полюdestination.booked_by— кто напечатал этикетку:anivaилиexternal. Только отправленияanivaподдерживают Обновить и Отменить; посылкаexternalотслеживается в том же списке, но возвращает501на оба запроса.
paired_with.
Доступ
- Ты можешь просматривать посылку, если хотя бы одна связанная запись или заказ набора для домашнего теста находится в твоём контексте доступа, либо если она отправлена из локации в твоём контексте доступа.
appointmentsиhome_kit_ordersсодержат только записи и заказы из твоего контекста доступа.- Для Обновить, Отменить, Привязать записи и Отвязать записи нужно, чтобы все связанные заказы наборов для домашнего теста входили в твой контекст доступа. Иначе вызов вернёт
403, и изменить посылку сможет только Aniva.
Чтение никогда не обращается к перевозчику
Каждый запрос на чтение обслуживается из нашей базы данных. Фоновая синхронизация сверяет каждое отправление с перевозчиком (каждые 10 минут для GO!, каждый час для DHL) и записываетsynced_at — это актуальность любого ответа. Принудительного обновления нет: DHL разрешает один запрос отслеживания раз в пять секунд, поэтому чтение с прямым обращением к перевозчику предложить нельзя.
Создание отправления
При создании отправления ты указываешь исходныйlocation_id — пункт сдачи, откуда курьер должен забрать посылку. Также ты указываешь целевую лабораторию в destination_lab. Отправление поедет на зарегистрированный адрес доставки этой лаборатории.
Локация должна входить в контекст доступа твоего API-ключа. Используй Список локаций, чтобы найти доступные идентификаторы локаций.
При желании ты можешь передать appointment_id, чтобы привязать отправление к конкретной записи
при создании. Связь отображается напрямую с обеих сторон:
- у отправления — в виде массива
appointmentsиз элементов{ id, added_at }; - у записи — в виде массива
shipmentsиз элементов{ id, added_at }.
id ссылается на канонический эндпоинт с подробностями
(Получить запись /
Получить отправление) для получения полных данных — партнёры, которым нужно
отслеживать статус доставки по каждой записи, переходят по каждому элементу массива shipments этой записи к
эндпоинту с подробностями отправления.
Отправление может быть связано с несколькими записями, а запись — с несколькими
отправлениями. После создания управляй связями с помощью Привязать записи к
отправлению /
Отвязать записи от отправления. Каждое
изменение возвращает обновлённый список записей этого отправления.
Правило изменения такое: связи можно создавать или удалять, если ЛИБО запись уже прошла
забор крови (blood_drawn), либо отправление создано менее 24 часов назад. Вне этого
окна связь блокируется, чтобы исторические данные оставались неизменными.
Жизненный цикл
Отправления проходят через следующие статусы:
При каждом изменении статуса отправляется вебхук
shipment.*, например
shipment.delivered. shipment.updated срабатывает при любом изменении, которое ты можешь прочитать, например при новом сканировании.
Правила расписания забора
При создании или обновлении расписания забора отправления действуют следующие правила.pickup_date
(YYYY-MM-DD) и pickup_time_from / pickup_time_till (HH:MM, 24-часовой формат) — это значения местного времени,
которые интерпретируются в часовом поясе IANA точки отправления — передавать часовой пояс вместе с ними не нужно.
Изменение отправлений
Ты можешь обновить расписание забора, количество посылок, вес и примечания к отправлению с помощьюPATCH /api/v1/shipments/{id}. Если изменится любое поле, важное для логистики (дата и время забора, количество посылок или вес), текущий логистический заказ автоматически отменяется и создаётся новый. Поля, которые ты не укажешь в теле запроса, сохраняются из существующего отправления — например, при обновлении только weight заказ пересоздастся с тем же расписанием забора. Обновлённые поля расписания проверяются по тем же правилам расписания забора.
Если логистический провайдер отклонит отмену или пересоздание заказа при обновлении, API вернёт 502 Bad Gateway с сообщением об ошибке от провайдера.
Отмена отправлений
Отмени отправление с помощьюDELETE /api/v1/shipments/{id}. Запрос обращается к API логистического провайдера для отмены заказа и меняет статус на cancelled.
Логистический провайдер также может отклонить отмену по своим причинам (например, прошёл крайний срок отмены). В этом случае API вернёт 502 Bad Gateway с сообщением и кодом ошибки провайдера.
Возвратные этикетки
Возвратная этикетка DHL входит в состав исходящего заказа. DHL не может отменить этикетку отдельно, поэтому отмена строки, отслеживающей возвратную этикетку, вернёт409 Conflict. Вместо этого отмени исходящую посылку, пока она в статусе pending. Вместе с ней отменится и этикетка: каждая строка обратной отправки этой посылки в статусе pending перейдёт в cancelled и получит запись RETURN_LEG_CANCELLED в своём status_updates. Обратная посылка, которую пациент уже отправил, продолжит движение. После отправки исходящей посылки этикетка остаётся действительной, а строку обратной отправки Aniva закрывает вручную.
Референсные ID отправлений
У каждого отправления есть референсный ID из 11 символов: буква, дата и четыре символа,{letter}YYMMDDXXXX (например, P2611194821). Буква показывает, к чему относится отправление, и никогда — его направление:
Отправление с 20 по 22 ноября 2026 года сохраняет свой ID со словом в начале:
API, MAN, AUTO или KIT (например, AUTO261121UWKX). Оба формата остаются действительными. Не проверяй длину или первую букву ID. Используй ID, чтобы получить, обновить или отменить отправление.
Адреса отправлений
Поляorigin и destination в ответе отправления содержат развёрнутые объекты адресов со следующей структурой:
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
после сканирования при передаче), поэтому одна лишь последняя запись не показывает, на каком этапе находится посылка.
Пример отправления
Пример посылок с домашним набором
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… возвращает в паре набор по пути к пациенту и образец на обратном пути:
pending, пока пациент не отправит образец — это реальное состояние, а не пробел.