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

# Szállítmányok listázása

> Szállítmányok lekérése időpont, otthoni készletrendelés vagy állapot alapján szűrve

Kérd le az API-kulcsod számára elérhető küldeményeket, a legújabbtól kezdve. Minden csomag ebben az egy listában szerepel:
a rendelőből történő futárfelvétel, az otthoni tesztkészletet rendelő pácienshez tartó készlet és a visszafelé
tartó minta. Szűrj egyetlen szülőelemre az `appointment_id` vagy a `home_kit_order_id` paraméterrel.

A `shipments_view` vagy a `shipments_manage` scope szükséges hozzá.

A válasz az adatbázisunkból érkezik, és soha nem hívja a futárszolgálatot. Egy háttérben futó szinkronizálás frissít minden
küldeményt (a GO! esetében 10 percenként, a DHL esetében óránként), az egyes sorokban található `synced_at` pedig megmutatja, mikor
kérdeztük le utoljára a futárszolgálatot.

## Kérés

### Lekérdezési paraméterek

**appointment\_id** `string`

Csak az ehhez az időponthoz kapcsolt küldemények (UUID). `404`, ha az időpont nem létezik, `403`,
ha a hozzáférési körödön kívül esik.

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

Csak az ehhez az otthoni tesztkészlet-rendeléshez kapcsolt küldemények (UUID). Általában két sor érkezik vissza – a pácienshez
tartó készlet és a laboratóriumba visszaküldött minta (a `destination` értéke a laboratórium). Ugyanazok a
`404` / `403` szabályok érvényesek, mint az `appointment_id` esetében.

**status** `string`

Csak az ebben az állapotban lévő küldemények. Az alábbiak egyike: `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

A visszaadható küldemények maximális száma. Alapértelmezés szerint 100, legfeljebb 500.

**offset** `integer`

Az átugorandó küldemények száma. Alapértelmezés szerint 0. A rendezés stabil (`created_at` szerint csökkenő, majd
hivatkozás szerint), így az oldalak nem fedik át egymást.

## Válasz

Siker esetén az API `200 OK` választ ad vissza a küldemény-objektumok tömbjével.

**id** `string` *required*

A küldemény referenciaazonosítója.

**status** `string` *required*

A küldemény életciklus-állapota. A következő értékek egyike: `pending`, `in_transit`, `delivered`, `fault` vagy `cancelled`.

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

Logisztikai szolgáltató. Lehetséges értékei: `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` vagy `dhl_express`. Az otthoni tesztkészlet-csomag `dhl_parcel`, illetve `dhl_warenpost`, ha külföldre megy
Warenpost International küldeményként.

**tracking\_number** `string`

A logisztikai szolgáltatótól kapott külső csomagkövetési szám. Lehet `null`.

**contents** `string`

Szabad szöveges leírás a csomag tartalmáról, a létrehozáskor megadottak szerint (pl. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Csak tájékoztató jellegű — az, hogy a csomag laboratóriumba
tart-e, a `destination` mezőből, a párja pedig a `paired_with` mezőből olvasható ki. Lehet `null`.

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

Ki nyomtatta ki a címkét: `aniva` vagy `external`. Csak az `aniva` küldeményeknél használható a
[Módosítás](https://docs.anivahealth.com/hu/api/shipments/update-shipment.md) és a [Lemondás](https://docs.anivahealth.com/hu/api/shipments/cancel-shipment.md); az
`external` csomagot követjük, de mindkettőre `501` választ ad.

**paired\_with** `string`

Egy kétcsomagos szállítmány másik csomagjának hivatkozása – az a csomag, amely a visszaküldési
címkét vitte, és az a csomag, amelyet ez a címke hoz vissza. Mindkettőnél be van állítva. Egyirányú csomagnál `null`.

**origin** `object`

Felvételi cím. Lehet `null`.

**cím objektum**

**name** `string` *required*

Címzett, cég vagy helyszín neve.

**company\_name** `string`

Cég / c/o sor. Lehet `null`.

**street** `string` *required*

Utcanév, házszám nélkül.

**house\_number** `string`

Házszám. Lehet `null`.

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

Épület, lépcsőház vagy emelet. Lehet `null`.

**city** `string` *required*

Város.

**state** `string`

Állam vagy tartomány. Lehet `null`.

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

Irányítószám.

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

ISO 3166-1 alpha-2 országkód.

**phone** `string`

Kapcsolattartó telefonszáma. Lehet `null`.

**email** `string`

Kapcsolattartó e-mail-címe. Lehet `null`.

**destination** `object`

Kézbesítési cím. Ugyanolyan szerkezetű, mint az `origin`. Lehet `null`.

**pickup** `object`

Ütemezett felvételi időablak. Lehet `null`.

**pickup objektum**

**from** `string` *required*

A felvételi időablak kezdete UTC időpillanatként (ISO 8601, `Z` utótaggal).

**till** `string` *required*

A felvételi időablak vége UTC időpillanatként (ISO 8601, `Z` utótaggal).

**timezone** `string` *required*

A felvétel helyszínének IANA időzónája (pl. `Europe/Berlin`). Ezzel jelenítheted meg a `from` / `till` értékeket a felvétel helyszínének helyi idejében.

**notes** `string`

Opcionális megjegyzések. Lehet `null`.

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

Időrendi életciklus-események a logisztikai szolgáltatótól (a legrégebbitől kezdve). Üres tömb, ha a
szolgáltató még nem jelentett eseményt. Használd eseményenkénti megjelenítéshez, audithoz és a részletesebb futárszolgálati
jelzésekhez; az irányadó aktuális állapothoz a `status` mezőre támaszkodj.

**állapotfrissítés mezői**

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

Az esemény a küldeményállapotok szókészletében – `pending`, `in_transit`, `delivered` vagy
`fault` –, így a futárszolgálat kódjainak ismerete nélkül is értelmezheted az idővonalat. `null`, ha az
esemény nem hordoz állapotot (címke létrehozása, a futárszolgálat információ nélküli szkennelése, a mező
bevezetése előtt rögzített bejegyzések). Soha nem `cancelled`.

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

A futárszolgálat saját állapotkódja: a GO! esetében `GO10` / `GO90` / `GOY001`, a DHL esetében `VA` / `ZF` / `LA`
/ `ZU`. `null`, ha a futárszolgálat nem adott meg ilyet. A `status` különböző nyelvű változatai között is
állandó marad.

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

A futárszolgálat részletesebb kódja, ha létezik – a DHL `statusDetailed` értéke, pl. `CNRFC_NRQRD_ZF`
(postára átirányítva), `HLDCC_SERPT_LA` (ott átvehető), `DLVRD_SERPT_ZU`
(átvéve). `null` az ilyen kód nélküli futárszolgálatoknál.

**status** `string` *required*

A szolgáltatótól származó állapotcímke (szabad szöveg, pl. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

A kód magyarázata vagy a futárszolgálat hosszabb leírása. `null`, ha egyik sem létezik.

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

A szkennelés helye a futárszolgálat megnevezése szerint – egy GO! depó (`"HUB Niederaula"`) vagy egy
DHL város. Szabad szöveg, nem koordináta. `null`, ha a futárszolgálat nem jelentette.

**time** `string` *required*

Az esemény észlelésének időpontja (ISO 8601, a futárszolgálat által jelentett időeltolódással).

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

Az ehhez a küldeményhez kapcsolt időpontok, a legrégebben kapcsolttól kezdve. Minden elem `{ id, added_at }` formátumú;
a teljes időpontadatokhoz kérd le az egyes `id` értékeket az [Időpont lekérése](https://docs.anivahealth.com/hu/api/appointments/get-appointment.md) végponton. Üres tömb, ha nincs kapcsolt időpont.
Csak a hozzáférési körödben lévő időpontok szerepelnek a listában.

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

Az ehhez a küldeményhez kapcsolt otthoni tesztkészlet-rendelések, a legrégebben kapcsolttól kezdve, ugyancsak `{ id, added_at }` formátumban.
Kérd le az egyes `id` értékeket az [Otthoni tesztkészlet-rendelés lekérése](https://docs.anivahealth.com/hu/api/home-kit-orders/get-home-kit.md) végponton. Rendelői
csomagoknál üres tömb. Csak a hozzáférési körödben lévő rendelések szerepelnek a listában. Lásd:
[Hozzáférés](https://docs.anivahealth.com/hu/concepts/shipments.md#hozzaferes).

**synced\_at** `string`

A küldemény és a futárszolgálat utolsó egyeztetésének UTC időpontja. A lekérdezések soha nem hívják a
futárszolgálatot – a háttérben futó szinkronizálás tartja frissen a küldeményeket –, így ez mutatja a válasz korát. Az első
szinkronizálásig `null`.

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

Létrehozási időbélyeg (ISO 8601).

**updated\_at** `string`

Utolsó frissítés időbélyege (ISO 8601). Lehet `null`.

## Ismételt hívások

Az Aniva minden API-kulcshoz 5 percig tárolja ennek a végpontnak a válaszát. Ezen az időn belül egy ismételt hívás
a tárolt választ kapja vissza. A `Cache-Status` és az `Age` fejléc mutatja, hogy a válasz
tárolt, és mennyi idős.

Ha azonnal értesülni szeretnél egy változásról, iratkozz fel a `shipment.created` és a `shipment.updated` webhook-eseményekre.
Lásd: [Ismételt lekérdezések](https://docs.anivahealth.com/hu/concepts/webhooks.md#ismetelt-lekeresek).

## Hibaválaszok

| Státusz | Leírás |
| - | - |
| `400` | Érvénytelen lekérdezési paraméter. |
| `403` | Tiltott – hiányzó jogosultság, vagy a szűrt időpont / otthoni tesztkészlet-rendelés a hozzáférési körödön kívül esik. |
| `404` | A szűrt időpont vagy otthoni tesztkészlet-rendelés nem található. |
| `500` | Belső szerverhiba. |

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