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

# Przesyłki

> Jak działa logistyka w API Aniva: przesyłki próbek do laboratorium i paczki z domowymi zestawami testowymi, ze śledzeniem i statusem.

Przesyłka to jedna fizyczna paczka: odbiór kurierski z próbkami krwi z lokalizacji badania do laboratorium, domowy zestaw testowy w drodze do pacjenta albo próbka, którą pacjent odsyła. API przesyłek pozwala ci tworzyć, śledzić, modyfikować i anulować zlecenia przesyłek oraz wyświetla w jednym miejscu każdą paczkę, niezależnie od tego, kto ją zamówił.

## Jedna lista z filtrowaniem

`GET /api/v1/shipments` to jedyna kolekcja. Przesyłka istnieje niezależnie — ma relację wiele do wielu z wizytami i może należeć do zamówienia domowego zestawu testowego — dlatego nie ma listy zagnieżdżonej pod obiektem nadrzędnym. Zawęź tę samą listę parametrami `?appointment_id=` lub `?home_kit_order_id=`, podziel ją na strony za pomocą `limit` / `offset`, a gdy masz konkretne ID, przejdź z wbudowanej tablicy `shipments` obiektu nadrzędnego (`{ id, added_at }` zarówno w wizytach, jak i w zamówieniach domowego zestawu testowego) do [Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md).

## Zawartość i kto zamówił przesyłkę

Każda przesyłka zawiera dwie informacje, których nie widać w jej adresach:

* `contents` — dowolny tekst opisujący zawartość paczki, ustawiany przy tworzeniu (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) i widoczny dla kuriera. Ma charakter wyłącznie informacyjny. Kierunek nie jest osobnym polem: o tym, czy paczka zmierza do laboratorium, informuje pole `destination`.
* `booked_by` — kto wydrukował etykietę: `aniva` lub `external`. Tylko przesyłki `aniva` obsługują [Zaktualizuj](https://docs.anivahealth.com/pl/api/shipments/update-shipment.md) i [Anuluj](https://docs.anivahealth.com/pl/api/shipments/cancel-shipment.md); paczka `external` jest śledzona na tej samej liście, ale dla obu tych operacji zwraca `501`.

Paczka, w której wysłano etykietę zwrotną, i paczka wracająca z tą etykietą wskazują na siebie nawzajem przez pole `paired_with`.

## Dostęp

* Możesz odczytać paczkę, gdy co najmniej jedna powiązana wizyta lub jedno zamówienie domowego zestawu testowego znajduje się w twoim kontekście dostępu, albo gdy paczka została nadana z lokalizacji w twoim kontekście dostępu.
* `appointments` i `home_kit_orders` zawierają wyłącznie wizyty i zamówienia z twojego kontekstu dostępu.
* [Zaktualizuj](https://docs.anivahealth.com/pl/api/shipments/update-shipment.md), [Anuluj](https://docs.anivahealth.com/pl/api/shipments/cancel-shipment.md), [Przypisz wizyty](https://docs.anivahealth.com/pl/api/shipments/attach-appointments-to-shipment.md) i [Odłącz wizyty](https://docs.anivahealth.com/pl/api/shipments/detach-appointments-from-shipment.md) wymagają, aby każde powiązane zamówienie domowego zestawu testowego znajdowało się w twoim kontekście dostępu. W przeciwnym razie wywołanie zwraca `403`, a paczkę może zmienić tylko Aniva.

## Odczyty nigdy nie odpytują przewoźnika

Każdy odczyt pochodzi z naszej bazy danych. Synchronizacja w tle uzgadnia każdą przesyłkę z jej przewoźnikiem (co 10 minut dla GO!, co godzinę dla DHL) i zapisuje znacznik `synced_at`, który pokazuje aktualność odpowiedzi. Nie ma wymuszonego odświeżania — DHL pozwala na jedno zapytanie śledzące co pięć sekund, więc nie możemy oferować odczytu łączącego się bezpośrednio z przewoźnikiem.

## Tworzenie przesyłki

Tworząc przesyłkę, podajesz źródłowe `location_id` — lokalizację badania, z której kurier ma odebrać paczkę. W polu `destination_lab` wskazujesz też docelowe laboratorium. Przesyłka trafia na zarejestrowany adres wysyłkowy tego laboratorium.

Lokalizacja musi należeć do kontekstu dostępu twojego klucza API. Użyj [Pobierz listę lokalizacji](https://docs.anivahealth.com/pl/api/locations/list-locations.md), aby znaleźć dostępne identyfikatory lokalizacji.

Opcjonalnie możesz przekazać `appointment_id`, aby powiązać przesyłkę z konkretną wizytą już przy
tworzeniu. Powiązanie pojawia się bezpośrednio po obu stronach:

* w przesyłce jako tablica `appointments` z wpisami `{ id, added_at }`;
* w wizycie jako tablica `shipments` z wpisami `{ id, added_at }`.

Obie tablice są posortowane od najstarszego powiązania. Każde `id` odsyła do kanonicznego punktu końcowego ze szczegółami
([Pobierz wizytę](https://docs.anivahealth.com/pl/api/appointments/get-appointment.md) /
[Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md)) po pełne dane — partnerzy, którzy chcą śledzić
postęp przesyłki dla danej wizyty, przechodzą z każdego wpisu w tablicy `shipments` wizyty do
punktu końcowego ze szczegółami przesyłki.

Przesyłkę można powiązać z wieloma wizytami, a wizytę z wieloma
przesyłkami. Po utworzeniu zarządzaj powiązaniami za pomocą [Przypisz wizyty do
przesyłki](https://docs.anivahealth.com/pl/api/shipments/attach-appointments-to-shipment.md) /
[Odłącz wizyty od przesyłki](https://docs.anivahealth.com/pl/api/shipments/detach-appointments-from-shipment.md). Każda
operacja zwraca listę wizyt przesyłki po zmianie.

Zasada modyfikacji jest taka: powiązania można tworzyć lub usuwać, gdy ALBO wizyta jest po
pobraniu krwi (`blood_drawn`), albo przesyłka została utworzona mniej niż 24 godziny temu. Poza tym
oknem powiązanie jest zablokowane, aby dane historyczne pozostały spójne.

## Cykl życia

Przesyłki przechodzą przez następujące statusy:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Status | Znaczenie |
| - | - |
| `pending` | Zlecenie kurierskie zostało złożone i czeka na odbiór. |
| `in_transit` | Kurier odebrał paczkę i jest ona w drodze. |
| `delivered` | Paczka została dostarczona. |
| `fault` | Podczas transportu wystąpił problem lub przewoźnik odesłał paczkę do nadawcy. |
| `cancelled` | Przesyłka została anulowana. |

Każda zmiana statusu wysyła [webhook](https://docs.anivahealth.com/pl/concepts/webhooks.md) `shipment.*`, na przykład
`shipment.delivered`. `shipment.updated` uruchamia się przy każdej zmianie, którą możesz odczytać, na przykład przy nowym skanie.

## Zasady harmonogramu odbioru

Poniższe zasady obowiązują podczas tworzenia lub aktualizowania harmonogramu odbioru przesyłki. `pickup_date`
(`YYYY-MM-DD`) oraz `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 h) to wartości czasu zegarowego
**interpretowane w strefie czasowej IANA lokalizacji nadania** — nie przesyłasz wraz z nimi strefy czasowej.

| Zasada | Szczegóły |
| - | - |
| **Tylko dni robocze** | `pickup_date` musi wypadać od poniedziałku do piątku. |
| **Dzisiaj lub później** | `pickup_date` nie może być w przeszłości. |
| **Limit na ten sam dzień** | Odbiory tego samego dnia są odrzucane po 16:00 Europe/Berlin. |
| **Zakres okna** | `pickup_time_from` i `pickup_time_till` muszą mieścić się w przedziale 09:00–19:00. |
| **Okno minimum 2 h** | Okno odbioru musi trwać co najmniej 2 godziny. |

## Modyfikowanie przesyłek

Możesz zaktualizować harmonogram odbioru, liczbę paczek, wagę i uwagi przesyłki za pomocą `PATCH /api/v1/shipments/{id}`. Jeśli zmieni się którekolwiek z pól istotnych dla logistyki (data odbioru, godzina, liczba paczek lub waga), dotychczasowe zlecenie logistyczne jest automatycznie anulowane i tworzone jest nowe. Pola pominięte w treści aktualizacji pozostają takie jak w istniejącej przesyłce — na przykład zaktualizowanie samego pola `weight` ponownie utworzy zlecenie z tym samym harmonogramem odbioru. Zaktualizowane pola harmonogramu są sprawdzane według tych samych [zasad harmonogramu odbioru](#zasady-harmonogramu-odbioru).

> [!WARNING]
>
> Przesyłek nie można modyfikować po odebraniu paczki przez kuriera. Próby aktualizacji
> przesyłki w statusie `in_transit`, `delivered` lub `fault` zwracają `409 Conflict`.

Jeśli dostawca logistyczny odrzuci anulowanie lub ponowne utworzenie zlecenia podczas aktualizacji, API zwraca `502 Bad Gateway` z komunikatem błędu dostawcy.

## Anulowanie przesyłek

Anuluj przesyłkę za pomocą `DELETE /api/v1/shipments/{id}`. Wywołuje to API dostawcy logistycznego, aby anulować zlecenie, i zmienia status na `cancelled`.

> [!WARNING]
>
> Przesyłek nie można anulować po odbiorze. Próby anulowania przesyłki, która ma już status
> `in_transit`, `delivered` lub `fault`, zwracają `409 Conflict`. Anulowanie przesyłki ze statusem
> `cancelled` nic nie zmienia i zwraca `200` z przesyłką — zobacz
> [Idempotencja](https://docs.anivahealth.com/pl/concepts/idempotency.md).

Dostawca logistyczny może też odrzucić anulowanie z własnych powodów (np. minął termin anulowania). W takim przypadku API zwraca `502 Bad Gateway` z komunikatem i kodem błędu dostawcy.

### Etykiety zwrotne

Etykieta zwrotna DHL jest częścią zlecenia wysyłkowego. DHL nie może anulować samej etykiety, więc anulowanie wpisu śledzącego etykietę zwrotną zwraca `409 Conflict`. Zamiast tego anuluj przesyłkę wychodzącą, dopóki ma status `pending`. Anuluje to również etykietę: każdy wpis przesyłki zwrotnej o statusie `pending` powiązany z paczką wychodzącą zmienia status na `cancelled` i otrzymuje wpis `RETURN_LEG_CANCELLED` w `status_updates`. Paczka zwrotna, którą pacjent już nadał, jedzie dalej. Po wysłaniu paczki wychodzącej etykieta pozostaje ważna, a Aniva zamyka wpis przesyłki zwrotnej ręcznie.

## Identyfikatory referencyjne przesyłek

Każda przesyłka ma 11-znakowy identyfikator referencyjny: literę, datę i cztery znaki, `{letter}YYMMDDXXXX` (na przykład `P2611194821`). Litera wskazuje, do czego należy przesyłka, a nigdy jej kierunek:

| Litera | Przesyłka |
| - | - |
| `P` | Przesyłka, którą tworzysz przez to API. |
| `M` | Przesyłka, którą tworzy zespół Aniva. |
| `C` | Przesyłka z codziennej wysyłki Aniva. |
| `K` | Paczka z zestawem domowym. |
| `F`, `S` | Własne paczki magazynowe Aniva. |

Przesyłka z dni 20–22 listopada 2026 r. zachowuje swój identyfikator ze słowem na początku: `API`, `MAN`, `AUTO` lub `KIT` (na przykład `AUTO261121UWKX`). Oba formaty pozostają ważne. Nie sprawdzaj długości ani pierwszej litery identyfikatora. Użyj identyfikatora, aby pobrać, zaktualizować lub anulować przesyłkę.

## Adresy przesyłki

Pola `origin` i `destination` w odpowiedzi przesyłki zawierają pełne obiekty adresowe o następującej strukturze:

```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"
}
```

W przypadku paczki z gabinetu adres `origin` jest ustalany na podstawie lokalizacji badania podanej przy
tworzeniu, a `destination` to laboratorium wskazane w `destination_lab`.
W przypadku paczki z zestawem domowym adres dostawy pacjenta jest polem `destination` zestawu i
polem `origin` zwrotu próbki; miejscem `origin` zestawu jest punkt, który go pakuje.
Adres nie zawiera `location_id` — powiąż paczkę z gabinetu za pomocą przypisanej do niej
wizyty.

## Okno odbioru

Pole `pickup` w odpowiedzi przesyłki zawiera zaplanowane okno odbioru kurierskiego.
Obejmuje znaczniki czasu `from` i `till` w UTC (ISO 8601 z sufiksem `Z`, np.
`2026-04-15T07:00:00Z`) oraz ciąg `timezone` (strefa czasowa IANA lokalizacji odbioru).
Wartości czasu zegarowego `pickup_date` / `pickup_time_*` wysłane podczas tworzenia lub aktualizacji są przeliczane na te
bezwzględne punkty w czasie z użyciem tej strefy czasowej — użyj `timezone`, aby ponownie wyświetlić `from` / `till`
jako czas lokalny w miejscu odbioru. Pole ma wartość `null`, gdy nie zaplanowano okna odbioru.

## Dziennik zmian statusu

Każda przesyłka ma tablicę `status_updates` — wszystkie zdarzenia cyklu życia zgłoszone przez dostawcę
logistycznego, od najstarszego. Każdy wpis zawiera:

* `state` — zdarzenie w słowniku statusów przesyłki (`pending`, `in_transit`, `delivered`,
  `fault`), dzięki czemu odczytasz oś czasu bez znajomości kodów przewoźnika. `null`, gdy zdarzenie
  nie ma przypisanego stanu (utworzenie etykiety, skan przewoźnika o braku informacji, wpisy zapisane przed
  wprowadzeniem tego pola). Nigdy `cancelled` — anulowanie pochodzi od nas, nie od przewoźnika.
* `code` — własny kod statusu przewoźnika (`GO10`, `GO90`, `GOY001` w GO!; `VA`, `ZF`,
  `LA`, `ZU` w DHL). `null`, gdy przewoźnik go nie podał. Pozostaje niezmienny niezależnie od języka
  pola `status`.
* `detail_code` — bardziej szczegółowy kod przewoźnika, jeśli istnieje: `statusDetailed` w DHL, np.
  `CNRFC_NRQRD_ZF` (przekierowano do placówki pocztowej), `HLDCC_SERPT_LA` (gotowa do odbioru na miejscu),
  `DLVRD_SERPT_ZU` (odebrana). W pozostałych przypadkach `null`.
* `status` — czytelna dla człowieka etykieta przewoźnika (np. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — wyjaśnienie kodu lub dłuższy komunikat przewoźnika. `null`, gdy
  żadne z nich nie istnieje.
* `location` — miejsce skanowania według nazwy przewoźnika: magazyn GO!, miasto w DHL. Zwykły
  tekst, a nie współrzędne.
* `time` — znacznik czasu zdarzenia w formacie ISO 8601 zgłoszony przez przewoźnika (wraz z przesunięciem strefowym).

Gdy przewoźnik odsyła paczkę do nadawcy, na osi czasu pojawia się wpis z polem `code`
`RETURNED_TO_SENDER`. Jego `status` zawiera powód podany przez przewoźnika. Przesyłka zachowuje status `fault`, również
po dostarczeniu paczki z powrotem do nas.

Lista może być pusta, jeśli przewoźnik nie zgłosił jeszcze żadnych zdarzeń.

Aby sprawdzić właściwy bieżący stan, użyj głównego pola `status`. Przechodzi ono w jednym kierunku — od `pending`
przez `in_transit` do `delivered` — z nakładanym stanem `fault`, gdy najnowsze zdarzenie zgłasza problem;
przewoźnicy nie sortują zdarzeń według ich wagi (DHL dopisuje powiadomienie o przekierowaniu z kodem `pre-transit`
już po skanie przekazania), więc sam najnowszy wpis nie mówi, na jakim etapie jest paczka.

## Przykładowa przesyłka

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

## Przykładowe paczki z zestawem domowym

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` zwraca w parze zestaw w drodze do pacjenta oraz próbkę w drodze powrotnej:

```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
  }
]
```

Wpis przesyłki zwrotnej istnieje od momentu wydrukowania etykiety zwrotnej i pozostaje w statusie `pending`, dopóki pacjent nie nada próbki — to rzeczywisty stan, a nie luka.


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