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

# Lista försändelser

> Hämta försändelser, filtrerade efter bokning, beställning av hemmakit eller status

Hämta de försändelser som din API-nyckel har åtkomst till, nyast först. Alla paket finns i den här enda listan:
en budhämtning från en mottagning, kitet på väg till en patient med hemtestkit och provet på
väg tillbaka. Filtrera till en överordnad post med `appointment_id` eller `home_kit_order_id`.

Kräver scope `shipments_view` eller `shipments_manage`.

Svaret kommer från vår databas och anropar aldrig transportören. En bakgrundssynkronisering uppdaterar varje
försändelse (var 10:e minut för GO!, varje timme för DHL) och `synced_at` på varje rad visar när
transportören senast tillfrågades.

## Förfrågan

### Frågeparametrar

**appointment\_id** `string`

Endast försändelser kopplade till den här bokningen (UUID). `404` när bokningen inte finns, `403`
när den ligger utanför din åtkomstkontext.

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

Endast försändelser kopplade till den här beställningen av hemtestkit (UUID). Normalt kommer två
rader tillbaka – kitet på väg till patienten och provet tillbaka till laboratoriet (dess
`destination` är laboratoriet). Samma regler för `404` / `403` som för `appointment_id`.

**status** `string`

Endast försändelser med den här statusen. Ett av `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Maximalt antal försändelser att returnera. Standard är 100, max 500.

**offset** `integer`

Antal försändelser att hoppa över. Standard är 0. Sorteringen är stabil (`created_at` fallande,
sedan referens), så sidorna överlappar inte.

## Svar

Vid lyckat anrop returnerar API:et `200 OK` med en array av försändelseobjekt.

**id** `string` *required*

Försändelsens referensidentifierare.

**status** `string` *required*

Försändelsens livscykelstatus. Ett av `pending`, `in_transit`, `delivered`, `fault` eller `cancelled`.

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

Logistikleverantör. Ett av `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` eller `dhl_express`. Ett paket med hemtestkit använder `dhl_parcel`, eller `dhl_warenpost` när det skickas utomlands
som Warenpost International.

**tracking\_number** `string`

Externt spårningsnummer från logistikleverantören. Kan vara `null`.

**contents** `string`

Fritextbeskrivning av paketets innehåll så som den angavs när försändelsen skapades (t.ex. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Endast i informationssyfte — om ett paket är på väg till ett
laboratorium utläses från `destination`, och dess motpart från `paired_with`. Kan vara `null`.

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

Vem som skrev ut etiketten: `aniva` eller `external`. Endast `aniva`-försändelser tar emot
[Uppdatera](https://docs.anivahealth.com/sv/api/shipments/update-shipment.md) och [Avboka](https://docs.anivahealth.com/sv/api/shipments/cancel-shipment.md); ett
`external`-paket spåras men returnerar `501` vid båda.

**paired\_with** `string`

Referens till det andra paketet i en sändning med två paket – paketet som hade med en
returetikett och paketet som etiketten skickar tillbaka. Anges på båda. `null` för ett paket som
bara går åt ett håll.

**origin** `object`

Upphämtningsadress. Kan vara `null`.

**adressobjekt**

**name** `string` *required*

Mottagare, företag eller platsnamn.

**company\_name** `string`

Företag / c/o-rad. Kan vara `null`.

**street** `string` *required*

Gatunamn utan husnummer.

**house\_number** `string`

Husnummer. Kan vara `null`.

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

Byggnad, port eller våning. Kan vara `null`.

**city** `string` *required*

Stad.

**state** `string`

Delstat eller provins. Kan vara `null`.

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

Postnummer.

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

Landskod enligt ISO 3166-1 alpha-2.

**phone** `string`

Telefonnummer för kontakt. Kan vara `null`.

**email** `string`

E-postadress för kontakt. Kan vara `null`.

**destination** `object`

Leveransadress. Samma struktur som `origin`. Kan vara `null`.

**pickup** `object`

Schemalagt upphämtningsfönster. Kan vara `null`.

**pickup-objekt**

**from** `string` *required*

Start på upphämtningsfönstret som en UTC-tidpunkt (ISO 8601 med `Z`-suffix).

**till** `string` *required*

Slut på upphämtningsfönstret som en UTC-tidpunkt (ISO 8601 med `Z`-suffix).

**timezone** `string` *required*

IANA-tidszon för upphämtningsplatsen (t.ex. `Europe/Berlin`). Använd för att visa `from` / `till` i upphämtningsplatsens lokala tid.

**notes** `string`

Valfria anteckningar. Kan vara `null`.

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

Kronologiska livscykelhändelser från logistikleverantören (äldst först). Tom array om
leverantören inte har rapporterat några händelser ännu. Använd detta för händelsevyer i
gränssnittet, granskning och mer detaljerade signaler från transportören; förlita dig på
`status` för den aktuella huvudstatusen.

**fält för statusuppdatering**

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

Händelsen enligt försändelsens statusvokabulär – `pending`, `in_transit`, `delivered` eller
`fault` – så att du kan läsa en tidslinje utan att känna till transportörens koder. `null` när
händelsen inte har något tillstånd (när etiketten skapades, en skanning utan information från
transportören, poster registrerade innan det här fältet fanns). Aldrig `cancelled`.

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

Transportörens egen statuskod: GO!:s `GO10` / `GO90` / `GOY001`, DHL:s `VA` / `ZF` / `LA`
/ `ZU`. `null` när transportören inte skickade någon. Stabil oberoende av språköversättningar av
`status`.

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

Transportörens mer detaljerade kod där en sådan finns – DHL:s `statusDetailed`, t.ex. `CNRFC_NRQRD_ZF`
(omdirigerad till ett postombud), `HLDCC_SERPT_LA` (klar för upphämtning där), `DLVRD_SERPT_ZU`
(upphämtad). `null` för transportörer utan sådan kod.

**status** `string` *required*

Statusetikett från leverantören (fritext, t.ex. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

En förklaring av koden, eller transportörens längre beskrivning. `null` när inget av dem finns.

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

Var skanningen skedde, enligt transportörens benämning – en GO!-depå (`"HUB Niederaula"`) eller en
DHL-ort. Fritext, inte en koordinat. `null` när transportören inte rapporterade någon.

**time** `string` *required*

Tidpunkt då händelsen observerades (ISO 8601, med den tidsförskjutning som transportören rapporterade).

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

Bokningar kopplade till denna försändelse, äldsta kopplingen först. Varje post är `{ id, added_at }`;
slå upp varje `id` med [Hämta bokning](https://docs.anivahealth.com/sv/api/appointments/get-appointment.md) för hela
bokningsobjektet. Tom array när inga bokningar är kopplade.
Endast bokningarna i din åtkomstkontext listas.

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

Beställningar av hemtestkit kopplade till denna försändelse, äldsta kopplingen först, med samma struktur `{ id, added_at }`.
Slå upp varje `id` med [Hämta beställning av hemtestkit](https://docs.anivahealth.com/sv/api/home-kit-orders/get-home-kit.md). Tom
array för paket från mottagningar. Endast beställningarna i din åtkomstkontext listas. Se
[Åtkomst](https://docs.anivahealth.com/sv/concepts/shipments.md#atkomst).

**synced\_at** `string`

När försändelsen senast stämdes av mot transportören, som en UTC-tidpunkt. Läsningar anropar aldrig
transportören – en bakgrundssynkronisering håller försändelserna uppdaterade – så det här visar hur gammalt svaret är. `null` fram till
den första synkroniseringen.

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

Tidsstämpel för skapande (ISO 8601).

**updated\_at** `string`

Tidsstämpel för senaste uppdatering (ISO 8601). Kan vara `null`.

## Upprepade anrop

Aniva lagrar svaret från den här slutpunkten i 5 minuter per API-nyckel. Ett upprepat anrop inom
den tiden får det lagrade svaret. Headerna `Cache-Status` och `Age` visar att svaret är
lagrat och hur gammalt det är.

För att få veta om en ändring direkt, prenumerera på webhook-händelserna `shipment.created` och `shipment.updated`.
Se [Upprepade läsningar](https://docs.anivahealth.com/sv/concepts/webhooks.md#upprepade-laesningar).

## Felsvar

| Status | Beskrivning |
| - | - |
| `400` | Ogiltig frågeparameter. |
| `403` | Förbjudet – saknar scope, eller så ligger den filtrerade bokningen eller beställningen av hemtestkit utanför ditt scope. |
| `404` | Den filtrerade bokningen eller beställningen av hemtestkit hittades inte. |
| `500` | Internt serverfel. |

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