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

# Forsendelser

> Sådan fungerer logistik i Anivas API: prøveforsendelser til laboratoriet og pakker med hjemmetestkits, med sporing og status.

En forsendelse er én fysisk pakke: en kurerafhentning med blodprøver fra en testlokation til et laboratorium, kittet på vej til en patient med hjemmetestkit eller prøven, som patienten sender retur. Forsendelses-API'et lader dig oprette, spore, ændre og annullere forsendelsesordrer og samler alle pakker ét sted, uanset hvem der har booket dem.

## Én liste, filtreret

`GET /api/v1/shipments` er den eneste samling. En forsendelse står alene — den har et mange-til-mange-forhold til tider og kan tilhøre en hjemmetestkitordre — så der findes ingen liste indlejret under et overordnet objekt. Indsnævr den samme liste med `?appointment_id=` eller `?home_kit_order_id=`, paginer den med `limit` / `offset`, og følg et overordnet objekts inline `shipments`-array (`{ id, added_at }` på både tider og hjemmetestkitordrer) til [Hent forsendelse](https://docs.anivahealth.com/da/api/shipments/get-shipment.md), når du har ét id.

## Indhold, og hvem der bookede den

Hver forsendelse indeholder to oplysninger, som ikke fremgår af adresserne:

* `contents` — fritekst, der beskriver, hvad der er i pakken, angivet ved oprettelse (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) og vist til kureren. Kun til information. Retning er ikke et felt: om en pakke er på vej til et laboratorium, aflæses af `destination`.
* `booked_by` — hvem der udskrev labelen: `aniva` eller `external`. Kun `aniva`-forsendelser accepterer [Opdater](https://docs.anivahealth.com/da/api/shipments/update-shipment.md) og [Annuller](https://docs.anivahealth.com/da/api/shipments/cancel-shipment.md); en `external`-pakke spores i den samme liste, men returnerer `501` på begge.

En pakke, der indeholdt en returlabel, og den pakke, som labelen sender retur, peger på hinanden via `paired_with`.

## Adgang

* Du kan læse en pakke, når mindst én tilknyttet tid eller hjemmetestkitordre er i din adgangskontekst, eller når den blev afsendt fra en lokation i din adgangskontekst.
* `appointments` og `home_kit_orders` viser kun de tider og ordrer, der er i din adgangskontekst.
* [Opdater](https://docs.anivahealth.com/da/api/shipments/update-shipment.md), [Annuller](https://docs.anivahealth.com/da/api/shipments/cancel-shipment.md), [Tilknyt tider](https://docs.anivahealth.com/da/api/shipments/attach-appointments-to-shipment.md) og [Fjern tider](https://docs.anivahealth.com/da/api/shipments/detach-appointments-from-shipment.md) kræver, at alle tilknyttede hjemmetestkitordrer er i din adgangskontekst. Ellers returnerer kaldet `403`, og kun Aniva kan ændre pakken.

## Læsninger kalder aldrig fragtfirmaet

Hver læsning besvares fra vores database. En baggrundssynkronisering afstemmer hver forsendelse med fragtfirmaet (hvert 10. minut for GO!, hver time for DHL) og sætter `synced_at`, som viser, hvor gammelt et svar er. Der findes ingen tvungen opdatering — DHL tillader ét sporingskald hvert femte sekund, så en læsning, der kaldte fragtfirmaet direkte, kan ikke tilbydes.

## Opret en forsendelse

Når du opretter en forsendelse, angiver du oprindelsens `location_id` — den testlokation, hvor kureren skal afhente. Du angiver også destinationslaboratoriet med `destination_lab`. Forsendelsen sendes til det pågældende laboratoriums registrerede forsendelsesadresse.

Lokationen skal være inden for din API-nøgles adgangskontekst. Brug [Vis lokationer](https://docs.anivahealth.com/da/api/locations/list-locations.md) til at finde tilgængelige lokations-id'er.

Du kan valgfrit sende `appointment_id` med for at knytte forsendelsen til en bestemt tid ved
oprettelse. Tilknytningen vises inline på begge sider:

* på forsendelsen som et `appointments`-array med `{ id, added_at }`-elementer;
* på tiden som et `shipments`-array med `{ id, added_at }`-elementer.

Begge arrays har ældste tilknytning først. Hvert `id` krydsrefererer til det kanoniske detaljeendpoint
([Hent tid](https://docs.anivahealth.com/da/api/appointments/get-appointment.md) /
[Hent forsendelse](https://docs.anivahealth.com/da/api/shipments/get-shipment.md)) for den fulde payload — partnere, der ønsker
kurerstatus pr. tid, følger hvert element i tidens `shipments`-array til
forsendelsens detaljeendpoint.

En forsendelse kan være knyttet til flere tider, og en tid kan være knyttet til flere
forsendelser. Efter oprettelse administrerer du tilknytningen med [Tilknyt tider til
forsendelse](https://docs.anivahealth.com/da/api/shipments/attach-appointments-to-shipment.md) /
[Fjern tider fra forsendelse](https://docs.anivahealth.com/da/api/shipments/detach-appointments-from-shipment.md). Hver
ændring returnerer forsendelsens opdaterede liste over tider.

Reglen for ændringer er: tilknytninger kan oprettes eller fjernes, når ENTEN tiden er efter
blodprøvetagning (`blood_drawn`), eller forsendelsen blev oprettet for mindre end 24 timer siden. Uden for det
vindue er tilknytningen låst, så historiske data forbliver stabile.

## Livscyklus

Forsendelser gennemgår følgende statusser:

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

| Status | Betydning |
| - | - |
| `pending` | Kurerordren er oprettet og afventer afhentning. |
| `in_transit` | Kureren har afhentet pakken, og den er undervejs. |
| `delivered` | Pakken er leveret. |
| `fault` | Der opstod et problem under transporten, eller fragtfirmaet sendte pakken tilbage til afsenderen. |
| `cancelled` | Forsendelsen er annulleret. |

Hver statusændring sender en `shipment.*`-[webhook](https://docs.anivahealth.com/da/concepts/webhooks.md), for eksempel
`shipment.delivered`. `shipment.updated` udløses ved hver ændring, du kan læse, som en ny scanning.

## Regler for afhentningstidspunkt

Følgende regler gælder, når du opretter eller opdaterer en forsendelses afhentningstidspunkt. `pickup_date`
(`YYYY-MM-DD`) og `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 t) er lokale tidspunkter, der
**fortolkes i afsendelsesstedets IANA-tidszone** – du sender ikke en tidszone med.

| Regel | Detalje |
| - | - |
| **Kun hverdage** | `pickup_date` skal være mandag–fredag. |
| **I dag eller fremover** | `pickup_date` må ikke ligge i fortiden. |
| **Frist for samme dag** | Afhentninger samme dag afvises efter kl. 16:00 Europe/Berlin. |
| **Tidsinterval** | `pickup_time_from` og `pickup_time_till` skal ligge inden for 09:00–19:00. |
| **Mindst 2 timers vindue** | Afhentningsvinduet skal være mindst 2 timer langt. |

## Ændring af forsendelser

Du kan opdatere en forsendelses afhentningstidspunkt, antal pakker, vægt og noter med `PATCH /api/v1/shipments/{id}`. Hvis et logistikrelevant felt ændres (afhentningsdato, tidspunkt, antal pakker eller vægt), bliver den eksisterende logistikordre automatisk annulleret, og en ny oprettes. Felter, du udelader i opdateringens body, bevares fra den eksisterende forsendelse – hvis du for eksempel kun opdaterer `weight`, genoprettes ordren med det samme afhentningstidspunkt. Opdaterede tidsfelter valideres efter de samme [regler for afhentningstidspunkt](#regler-for-afhentningstidspunkt).

> [!WARNING]
>
> Forsendelser kan ikke ændres, når kureren har afhentet pakken. Forsøg på at opdatere en
> forsendelse med status `in_transit`, `delivered` eller `fault` returnerer `409 Conflict`.

Hvis logistikudbyderen afviser annulleringen eller genoprettelsen under en opdatering, returnerer API'et `502 Bad Gateway` med udbyderens fejlmeddelelse.

## Annullering af forsendelser

Annuller en forsendelse med `DELETE /api/v1/shipments/{id}`. Det kalder logistikudbyderens API for at annullere ordren og opdaterer status til `cancelled`.

> [!WARNING]
>
> Forsendelser kan ikke annulleres efter afhentning. Forsøg på at annullere en forsendelse, der allerede
> er `in_transit`, `delivered` eller `fault`, returnerer `409 Conflict`. At annullere en forsendelse, der allerede
> er `cancelled`, har ingen effekt og returnerer `200` med forsendelsen – se
> [Idempotens](https://docs.anivahealth.com/da/concepts/idempotency.md).

Logistikudbyderen kan også afvise annulleringen af egne grunde (fx hvis annulleringsfristen er udløbet). I så fald returnerer API'et `502 Bad Gateway` med udbyderens fejlmeddelelse og fejlkode.

### Returlabels

En DHL-returlabel er en del af den udgående ordre. DHL kan ikke annullere labelen alene, så annullering af den række, der sporer en returlabel, returnerer `409 Conflict`. Annuller i stedet den udgående pakke, mens den er `pending`. Det annullerer også labelen: Hver returrække med status `pending` for den udgående pakke bliver `cancelled` og får en `RETURN_LEG_CANCELLED`-post i sin `status_updates`. En returpakke, som patienten allerede har sendt, fortsætter uændret. Når den udgående pakke er afsendt, forbliver labelen gyldig, og Aniva lukker returrækken manuelt.

## Reference-id'er for forsendelser

Hver forsendelse har et reference-ID på 11 tegn: et bogstav, datoen og fire tegn, `{letter}YYMMDDXXXX` (for eksempel `P2611194821`). Bogstavet viser, hvad forsendelsen hører til, aldrig dens retning:

| Bogstav | Forsendelse |
| - | - |
| `P` | En forsendelse, du opretter via dette API. |
| `M` | En forsendelse, Aniva-teamet opretter. |
| `C` | En forsendelse fra Anivas daglige afsendelse. |
| `K` | En pakke med et hjemmekit. |
| `F`, `S` | Anivas egne lagerpakker. |

En forsendelse fra 20. til 22. november 2026 beholder sit ID med et ord foran: `API`, `MAN`, `AUTO` eller `KIT` (for eksempel `AUTO261121UWKX`). Begge former forbliver gyldige. Tjek ikke længden eller det første bogstav i et ID. Brug ID'et til at hente, opdatere eller annullere forsendelsen.

## Forsendelsesadresser

Felterne `origin` og `destination` i forsendelsessvaret indeholder opslåede adresseobjekter med følgende struktur:

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

For en klinikpakke slås `origin`-adressen op ud fra det teststed, du angav ved
oprettelsen, og `destination` er det laboratorium, du angav i `destination_lab`.
For en hjemmekitpakke er patientens leveringsadresse kittets `destination` og
`origin` for returforsendelsen af prøven; det sted, der pakker kittet, er kittets `origin`.
Adressen indeholder intet `location_id` – match en klinikpakke via den tid, den er
knyttet til.

## Afhentningsvindue

Feltet `pickup` i forsendelsessvaret indeholder det planlagte afhentningsvindue for kureren. Det
omfatter tidsstemplerne `from` og `till` som UTC-tidspunkter (ISO 8601 med `Z`-suffiks, fx
`2026-04-15T07:00:00Z`) samt en `timezone`-streng (afhentningsstedets IANA-tidszone). De lokale
tidspunkter `pickup_date` / `pickup_time_*`, du sendte ved oprettelse/opdatering, omsættes til disse
absolutte tidspunkter ud fra den tidszone – brug `timezone` til at vise `from` / `till` tilbage i
afhentningsstedets lokale tid. Feltet er `null`, når der ikke er planlagt et afhentningsvindue.

## Log over statusopdateringer

Hver forsendelse har et `status_updates`-array – hver livscyklushændelse, logistikudbyderen har
rapporteret, med den ældste først. Hver post indeholder:

* `state` – hændelsen i forsendelsens statusvokabular (`pending`, `in_transit`, `delivered`,
  `fault`), så du kan læse en tidslinje uden at kende fragtfirmaets koder. `null`, når hændelsen
  ikke har nogen status (oprettelse af label, en fragtfirmascanning uden information, poster registreret før
  feltet fandtes). Aldrig `cancelled` – en annullering er vores, ikke en hændelse fra fragtfirmaet.
* `code` – fragtfirmaets egen statuskode (GO!'s `GO10`, `GO90`, `GOY001`; DHL's `VA`, `ZF`,
  `LA`, `ZU`). `null`, når fragtfirmaet ikke har angivet nogen. Stabil på tværs af sprogoversættelser af
  `status`.
* `detail_code` – fragtfirmaets mere detaljerede kode, når den findes: DHL's `statusDetailed`, fx
  `CNRFC_NRQRD_ZF` (omdirigeret til et posthus), `HLDCC_SERPT_LA` (klar til afhentning dér),
  `DLVRD_SERPT_ZU` (afhentet). `null` i andre tilfælde.
* `status` – fragtfirmaets læsbare tekst (fx `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` – en forklaring af koden eller fragtfirmaets længere beskrivelse. `null`, når
  ingen af delene findes.
* `location` – hvor scanningen skete, som fragtfirmaet angiver det: et GO!-depot, en DHL-by. Fri
  tekst, ikke et koordinat.
* `time` – ISO 8601-tidsstempel for hændelsen, som rapporteret af fragtfirmaet (med tidszoneforskydning).

Når fragtfirmaet sender pakken tilbage til afsenderen, får tidslinjen én post med `code`
`RETURNED_TO_SENDER`. Dens `status` indeholder fragtfirmaets årsag. Forsendelsen forbliver derefter `fault`, også
efter fragtfirmaet har leveret pakken tilbage til os.

Listen kan være tom, hvis fragtfirmaet endnu ikke har rapporteret nogen hændelser.

Brug `status`-feltet på øverste niveau for den gældende status. Den bevæger sig kun én vej – fra `pending`
til `in_transit` til `delivered` – med `fault` lagt ovenpå, mens den nyeste hændelse melder om en fejl;
fragtfirmaer sorterer ikke deres hændelser efter betydning (DHL tilføjer en `pre-transit`-kodet omdirigeringsbesked
efter overdragelsesscanningen), så den nyeste post alene viser ikke, hvor langt en pakke er.

## Eksempel på forsendelse

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

## Eksempel på hjemmekitpakker

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` returnerer kittet på vej til patienten og prøven på vej tilbage, parret:

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

Returrækken findes fra det øjeblik, returlabelen udskrives, og forbliver `pending`, indtil patienten sender prøven – det er den reelle status, ikke en mangel.


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