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

# Wyświetl listę przesyłek

> Pobierz przesyłki filtrowane według wizyty, zamówienia zestawu domowego lub statusu

Pobierz przesyłki dostępne dla twojego klucza API, od najnowszej. Na tej jednej liście znajdują się wszystkie paczki:
odbiór kurierski z gabinetu, domowy zestaw testowy w drodze do pacjenta oraz próbka w
drodze powrotnej. Filtruj do jednego obiektu nadrzędnego za pomocą `appointment_id` lub `home_kit_order_id`.

Wymaga zakresu `shipments_view` lub `shipments_manage`.

Odpowiedź pochodzi z naszej bazy danych i nigdy nie odpytuje przewoźnika. Synchronizacja w tle odświeża każdą
przesyłkę (co 10 minut dla GO!, co godzinę dla DHL), a pole `synced_at` w każdym wierszu informuje, kiedy
ostatnio odpytano przewoźnika.

## Żądanie

### Parametry zapytania

**appointment\_id** `string`

Tylko przesyłki powiązane z tą wizytą (UUID). `404`, gdy wizyta nie istnieje, `403`,
gdy znajduje się poza twoim kontekstem dostępu.

**home\_kit\_order\_id** `string`

Tylko przesyłki powiązane z tym zamówieniem domowego zestawu testowego (UUID). Zwykle zwracane są dwa wiersze — zestaw w
drodze do pacjenta oraz próbka wracająca do laboratorium (jej `destination` to laboratorium). Takie same
zasady `404` / `403` jak dla `appointment_id`.

**status** `string`

Tylko przesyłki o tym statusie. Jedna z wartości: `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Maksymalna liczba zwracanych przesyłek. Domyślnie 100, maks. 500.

**offset** `integer`

Liczba przesyłek do pominięcia. Domyślnie 0. Sortowanie jest stabilne (`created_at` malejąco, potem
numer referencyjny), więc strony nie nakładają się na siebie.

## Odpowiedź

W razie powodzenia API zwraca `200 OK` z tablicą obiektów przesyłek.

**id** `string` *required*

Identyfikator referencyjny przesyłki.

**status** `string` *required*

Status cyklu życia przesyłki. Jedna z wartości: `pending`, `in_transit`, `delivered`, `fault` lub `cancelled`.

**logistics\_provider** `string` *required*

Dostawca logistyczny. Jedna z wartości: `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` lub `dhl_express`. Paczka z zestawem domowym ma wartość `dhl_parcel` albo `dhl_warenpost`, gdy jest wysyłana za granicę
jako Warenpost International.

**tracking\_number** `string`

Zewnętrzny numer śledzenia od dostawcy logistycznego. Może mieć wartość `null`.

**contents** `string`

Dowolny opis zawartości paczki podany przy tworzeniu (np. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Ma charakter wyłącznie informacyjny — to, czy paczka zmierza do
laboratorium, odczytasz z `destination`, a jej odpowiednik z `paired_with`. Może mieć wartość `null`.

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

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, ale dla obu zwraca `501`.

**paired\_with** `string`

Numer referencyjny drugiej paczki w przesyłce dwupaczkowej — tej, która zawierała etykietę
zwrotną, i tej, która wraca z tą etykietą. Ustawione dla obu. `null` dla paczki w jedną stronę.

**origin** `object`

Adres odbioru. Może mieć wartość `null`.

**obiekt adresu**

**name** `string` *required*

Nazwa odbiorcy, firmy lub lokalizacji.

**company\_name** `string`

Firma / linia c/o. Może mieć wartość `null`.

**street** `string` *required*

Nazwa ulicy bez numeru domu.

**house\_number** `string`

Numer domu. Może mieć wartość `null`.

**address\_line\_2** `string`

Budynek, wejście lub piętro. Może mieć wartość `null`.

**city** `string` *required*

Miasto.

**state** `string`

Stan lub województwo. Może mieć wartość `null`.

**postal\_code** `string` *required*

Kod pocztowy.

**country\_code** `string` *required*

Kod kraju ISO 3166-1 alpha-2.

**phone** `string`

Kontaktowy numer telefonu. Może mieć wartość `null`.

**email** `string`

Kontaktowy adres e-mail. Może mieć wartość `null`.

**destination** `object`

Adres dostawy. Taka sama struktura jak `origin`. Może mieć wartość `null`.

**pickup** `object`

Zaplanowane okno odbioru. Może mieć wartość `null`.

**obiekt pickup**

**from** `string` *required*

Początek okna odbioru jako znacznik czasu UTC (ISO 8601 z przyrostkiem `Z`).

**till** `string` *required*

Koniec okna odbioru jako znacznik czasu UTC (ISO 8601 z przyrostkiem `Z`).

**timezone** `string` *required*

Strefa czasowa IANA miejsca odbioru (np. `Europe/Berlin`). Użyj jej, aby wyświetlić `from` / `till` w czasie lokalnym miejsca odbioru.

**notes** `string`

Opcjonalne notatki. Może mieć wartość `null`.

**status\_updates** `object[]` *required*

Chronologiczne zdarzenia cyklu życia przesyłki od dostawcy logistycznego (od najstarszego). Pusta
tablica, jeśli dostawca nie zgłosił jeszcze żadnych zdarzeń. Używaj tego pola do widoku zdarzeń,
audytu i szczegółowych sygnałów przewoźnika; kanoniczny bieżący stan odczytuj z `status`.

**pola aktualizacji statusu**

**state** `string | null` *required*

Zdarzenie w słowniku statusów przesyłki — `pending`, `in_transit`, `delivered` lub
`fault` — dzięki któremu odczytasz oś czasu bez znajomości kodów przewoźnika. `null`, gdy
zdarzenie nie niesie stanu (utworzenie etykiety, skan przewoźnika o braku informacji, wpisy
zapisane przed wprowadzeniem tego pola). Nigdy `cancelled`.

**code** `string | null` *required*

Własny kod statusu przewoźnika: w GO! `GO10` / `GO90` / `GOY001`, w DHL `VA` / `ZF` / `LA`
/ `ZU`. `null`, gdy przewoźnik go nie podał. Stały niezależnie od wersji językowej pola
`status`.

**detail\_code** `string | null` *required*

Bardziej szczegółowy kod przewoźnika, jeśli istnieje — w DHL to `statusDetailed`, np. `CNRFC_NRQRD_ZF`
(przekierowana na pocztę), `HLDCC_SERPT_LA` (gotowa do odbioru na miejscu), `DLVRD_SERPT_ZU`
(odebrana). `null` dla przewoźników bez takiego kodu.

**status** `string` *required*

Etykieta statusu od dostawcy (dowolny tekst, np. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Wyjaśnienie kodu albo dłuższy komunikat przewoźnika. `null`, gdy nie ma żadnego z nich.

**location** `string | null` *required*

Miejsce wykonania skanu według nazewnictwa przewoźnika — oddział GO! (`"HUB Niederaula"`) lub
miasto w DHL. Dowolny tekst, nie współrzędne. `null`, gdy przewoźnik go nie podał.

**time** `string` *required*

Czas zarejestrowania zdarzenia (ISO 8601, z przesunięciem strefy czasowej podanym przez przewoźnika).

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

Wizyty powiązane z tą przesyłką, od najstarszego powiązania. Każdy wpis ma postać `{ id, added_at }`;
każdy `id` sprawdź w [Pobierz wizytę](https://docs.anivahealth.com/pl/api/appointments/get-appointment.md), aby uzyskać
pełne dane wizyty. Pusta tablica, gdy żadne wizyty nie są powiązane.
Na liście są tylko wizyty w twoim kontekście dostępu.

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

Zamówienia domowych zestawów testowych powiązane z tą przesyłką, od najstarszego powiązania, w tej samej postaci `{ id, added_at }`.
Każdy `id` sprawdź w [Pobierz zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/get-home-kit.md). Pusta
tablica dla paczek z gabinetów. Na liście są tylko zamówienia w twoim kontekście dostępu. Zobacz
[Dostęp](https://docs.anivahealth.com/pl/concepts/shipments.md#dostep).

**synced\_at** `string`

Czas ostatniej synchronizacji przesyłki z przewoźnikiem jako znacznik czasu UTC. Odczyty nigdy nie
odpytują przewoźnika — dane odświeża synchronizacja w tle — więc to pokazuje, jak stara jest odpowiedź. `null` do
pierwszej synchronizacji.

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

Znacznik czasu utworzenia (ISO 8601).

**updated\_at** `string`

Znacznik czasu ostatniej aktualizacji (ISO 8601). Może mieć wartość `null`.

## Powtarzane wywołania

Aniva przechowuje odpowiedź tego punktu końcowego przez 5 minut dla każdego klucza API. Ponowne wywołanie w tym czasie
zwraca zapisaną odpowiedź. Nagłówki `Cache-Status` i `Age` pokazują, że odpowiedź jest
zapisana i jaki jest jej wiek.

Aby od razu dowiedzieć się o zmianie, zasubskrybuj zdarzenia webhooka `shipment.created` i `shipment.updated`.
Zobacz [Powtarzane odczyty](https://docs.anivahealth.com/pl/concepts/webhooks.md#powtarzane-odczyty).

## Odpowiedzi z błędami

| Status | Opis |
| - | - |
| `400` | Nieprawidłowy parametr zapytania. |
| `403` | Brak dostępu — brakujący zakres lub filtrowana wizyta / zamówienie domowego zestawu testowego jest poza twoim zakresem. |
| `404` | Nie znaleziono filtrowanej wizyty ani zamówienia domowego zestawu testowego. |
| `500` | Wewnętrzny błąd serwera. |

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