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

> Slik fungerer logistikk i Aniva-API-et: prøveforsendelser til laboratoriet og pakker med hjemmetestsett, med sporing og status.

En forsendelse er én fysisk pakke: en budhenting som frakter blodprøver fra et teststed til et laboratorium, settet på vei til en pasient med hjemmetestsett, eller prøven pasienten sender tilbake i posten. Shipments-API-et lar deg opprette, spore, endre og kansellere forsendelsesbestillinger, og viser alle pakker på ett sted uansett hvem som bestilte dem.

## Én liste, filtrert

`GET /api/v1/shipments` er den eneste samlingen. En forsendelse står alene – den har en mange-til-mange-relasjon til timer og kan tilhøre en bestilling av hjemmetestsett – så det finnes ingen liste nøstet under et overordnet objekt. Begrens den samme listen med `?appointment_id=` eller `?home_kit_order_id=`, paginer den med `limit` / `offset`, og følg den innebygde `shipments`-listen på det overordnede objektet (`{ id, added_at }` på både timer og bestillinger av hjemmetestsett) til [Hent forsendelse](https://docs.anivahealth.com/no/api/shipments/get-shipment.md) når du har én ID.

## Innhold og hvem som bestilte den

Hver forsendelse har to opplysninger som ikke er synlige ut fra adressene:

* `contents` – fritekst som beskriver hva som er i pakken, satt ved opprettelse (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) og vist til budet. Kun til informasjon. Retning er ikke et eget felt: om en pakke er på vei til et laboratorium, leses av `destination`.
* `booked_by` – hvem som skrev ut etiketten: `aniva` eller `external`. Bare `aniva`-forsendelser godtar [Oppdater](https://docs.anivahealth.com/no/api/shipments/update-shipment.md) og [Kanseller](https://docs.anivahealth.com/no/api/shipments/cancel-shipment.md); en `external`-pakke spores i den samme listen, men returnerer `501` på begge.

En pakke som inneholdt en returetikett, og pakken som den etiketten sender tilbake, peker på hverandre via `paired_with`.

## Tilgang

* Du kan lese en pakke når minst én koblet time eller bestilling av hjemmetestsett er i tilgangskonteksten din, eller når den ble sendt fra et sted i tilgangskonteksten din.
* `appointments` og `home_kit_orders` viser bare timene og bestillingene i tilgangskonteksten din.
* [Oppdater](https://docs.anivahealth.com/no/api/shipments/update-shipment.md), [Kanseller](https://docs.anivahealth.com/no/api/shipments/cancel-shipment.md), [Koble til timer](https://docs.anivahealth.com/no/api/shipments/attach-appointments-to-shipment.md) og [Koble fra timer](https://docs.anivahealth.com/no/api/shipments/detach-appointments-from-shipment.md) krever at alle koblede bestillinger av hjemmetestsett er i tilgangskonteksten din. Ellers returnerer kallet `403`, og bare Aniva kan endre pakken.

## Lesinger kaller aldri transportøren

Hver lesing besvares fra databasen vår. En bakgrunnssynkronisering avstemmer hver forsendelse med transportøren (hvert 10. minutt for GO!, hver time for DHL) og stempler `synced_at`, som viser hvor gammelt svaret er. Det finnes ingen tvungen oppdatering – DHL tillater ett sporingskall hvert femte sekund, så en lesing som går direkte til transportøren, kan ikke tilbys.

## Opprette en forsendelse

Når du oppretter en forsendelse, oppgir du avsenderens `location_id` – teststedet der budet skal hente pakken. Du oppgir også mottakerlaboratoriet med `destination_lab`. Forsendelsen sendes til det laboratoriets registrerte leveringsadresse.

Stedet må være innenfor tilgangskonteksten til API-nøkkelen din. Bruk [List opp steder](https://docs.anivahealth.com/no/api/locations/list-locations.md) for å finne tilgjengelige steds-ID-er.

Du kan valgfritt sende med `appointment_id` for å koble forsendelsen til en bestemt time ved
opprettelse. Koblingen vises innebygd på begge sider:

* på forsendelsen, som en `appointments`-liste med `{ id, added_at }`-elementer;
* på timen, som en `shipments`-liste med `{ id, added_at }`-elementer.

Begge listene har den eldste koblingen først. Hver `id` kryssrefererer til det kanoniske detaljendepunktet
([Hent time](https://docs.anivahealth.com/no/api/appointments/get-appointment.md) /
[Hent forsendelse](https://docs.anivahealth.com/no/api/shipments/get-shipment.md)) for hele payloaden – partnere som ønsker
budstatus per time, følger hvert element i timens `shipments`-liste til
detaljendepunktet for forsendelsen.

En forsendelse kan kobles til flere timer, og en time kan kobles til flere
forsendelser. Etter opprettelse administrerer du koblingene med [Koble timer til
forsendelse](https://docs.anivahealth.com/no/api/shipments/attach-appointments-to-shipment.md) /
[Koble timer fra forsendelse](https://docs.anivahealth.com/no/api/shipments/detach-appointments-from-shipment.md). Hver
endring returnerer forsendelsens timeliste etter endringen.

Regelen for endringer er: koblinger kan opprettes eller fjernes når ENTEN timen er forbi
blodprøvetaking (`blood_drawn`), eller forsendelsen ble opprettet for mindre enn 24 timer siden. Utenfor det
tidsvinduet er koblingen låst slik at historiske oppføringer forblir stabile.

## Livssyklus

Forsendelser går gjennom følgende statuser:

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

| Status | Betydning |
| - | - |
| `pending` | Budbestillingen er lagt inn og venter på henting. |
| `in_transit` | Budet har hentet pakken, og den er underveis. |
| `delivered` | Pakken er levert. |
| `fault` | Det oppsto et problem under transporten, eller transportøren sendte pakken tilbake til avsenderen. |
| `cancelled` | Forsendelsen er kansellert. |

Hver statusendring sender en `shipment.*`-[webhook](https://docs.anivahealth.com/no/concepts/webhooks.md), for eksempel
`shipment.delivered`. `shipment.updated` utløses ved hver endring du kan lese, som en ny skanning.

## Regler for hentetidspunkt

Følgende regler gjelder når du oppretter eller oppdaterer hentetidspunktet for en forsendelse. `pickup_date`
(`YYYY-MM-DD`) og `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24-timers) er lokale klokkeslett
**tolket i avsenderstedets IANA-tidssone** – du sender ikke med noen tidssone.

| Regel | Detalj |
| - | - |
| **Kun hverdager** | `pickup_date` må være mandag–fredag. |
| **I dag eller senere** | `pickup_date` kan ikke være i fortiden. |
| **Frist for samme dag** | Henting samme dag avvises etter 16:00 Europe/Berlin. |
| **Tillatt tidsrom** | `pickup_time_from` og `pickup_time_till` må være innenfor 09:00–19:00. |
| **Minst 2 timers vindu** | Hentevinduet må være minst 2 timer langt. |

## Endre forsendelser

Du kan oppdatere hentetidspunkt, antall pakker, vekt og notater for en forsendelse med `PATCH /api/v1/shipments/{id}`. Hvis logistikkrelevante felt endres (hentedato, tidspunkt, antall pakker eller vekt), blir den eksisterende logistikkbestillingen automatisk kansellert og en ny opprettet. Felt du utelater fra oppdateringsforespørselen, beholdes fra den eksisterende forsendelsen – hvis du for eksempel bare oppdaterer `weight`, opprettes bestillingen på nytt med samme hentetidspunkt. Oppdaterte tidsfelt valideres mot de samme [reglene for hentetidspunkt](#regler-for-hentetidspunkt).

> [!WARNING]
>
> Forsendelser kan ikke endres etter at budet har hentet pakken. Forsøk på å oppdatere en
> forsendelse med status `in_transit`, `delivered` eller `fault` returnerer `409 Conflict`.

Hvis logistikkleverandøren avviser kanselleringen eller nyopprettingen under en oppdatering, returnerer API-et `502 Bad Gateway` med leverandørens feilmelding.

## Kansellere forsendelser

Kanseller en forsendelse med `DELETE /api/v1/shipments/{id}`. Dette kaller logistikkleverandørens API for å kansellere bestillingen og oppdaterer statusen til `cancelled`.

> [!WARNING]
>
> Forsendelser kan ikke kanselleres etter henting. Forsøk på å kansellere en forsendelse som allerede er
> `in_transit`, `delivered` eller `fault`, returnerer `409 Conflict`. Å kansellere en som allerede er
> `cancelled`, gjør ingenting og returnerer `200` med forsendelsen – se
> [Idempotens](https://docs.anivahealth.com/no/concepts/idempotency.md).

Logistikkleverandøren kan også avvise kanselleringen av egne grunner (f.eks. at fristen for kansellering har gått ut). I så fall returnerer API-et `502 Bad Gateway` med leverandørens feilmelding og feilkode.

### Returetiketter

En DHL-returetikett er en del av den utgående bestillingen. DHL kan ikke kansellere etiketten alene, så å kansellere raden som sporer en returetikett returnerer `409 Conflict`. Kanseller heller den utgående pakken mens den er `pending`. Da kanselleres etiketten samtidig: hver `pending`-returrad for den utgående pakken blir `cancelled` og får en `RETURN_LEG_CANCELLED`-oppføring i `status_updates`. En returpakke som pasienten allerede har sendt, fortsetter som normalt. Etter at den utgående pakken er sendt, forblir etiketten gyldig, og Aniva lukker returraden manuelt.

## Referanse-ID-er for forsendelser

Hver forsendelse har en referanse-ID på 11 tegn: en bokstav, datoen og fire tegn, `{letter}YYMMDDXXXX` (for eksempel `P2611194821`). Bokstaven viser hva forsendelsen tilhører, aldri retningen:

| Bokstav | Forsendelse |
| - | - |
| `P` | En forsendelse som du oppretter via dette API-et. |
| `M` | En forsendelse som Aniva-teamet oppretter. |
| `C` | En forsendelse fra Anivas daglige utsendelse. |
| `K` | En pakke med hjemmesett. |
| `F`, `S` | Anivas egne lagerpakker. |

En forsendelse fra 20. til 22. november 2026 beholder ID-en sin med et ord foran: `API`, `MAN`, `AUTO` eller `KIT` (for eksempel `AUTO261121UWKX`). Begge formatene forblir gyldige. Ikke sjekk lengden eller den første bokstaven i en ID. Bruk ID-en til å hente, oppdatere eller kansellere forsendelsen.

## Forsendelsesadresser

Feltene `origin` og `destination` i forsendelsessvaret inneholder oppslåtte 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 praksispakke hentes `origin`-adressen fra teststedet du oppga ved
opprettelsen, og `destination` er laboratoriet du oppga i `destination_lab`.
For en hjemmetestpakke er pasientens leveringsadresse `destination` for testsettet og
`origin` for returen av prøven; stedet som pakker testsettet, er `origin` for det.
Adressen har ingen `location_id` – koble en praksispakke gjennom timen den er
knyttet til.

## Hentevindu

Feltet `pickup` i forsendelsessvaret inneholder det planlagte hentevinduet for budet. Det
inneholder tidsstemplene `from` og `till` som UTC-tidspunkter (ISO 8601 med `Z`-suffiks, f.eks.
`2026-04-15T07:00:00Z`) og en `timezone`-streng (hentestedets IANA-tidssone). De
lokale klokkeslettene i `pickup_date` / `pickup_time_*` du sendte ved opprettelse / oppdatering, konverteres til disse
absolutte tidspunktene med den tidssonen – bruk `timezone` for å vise `from` / `till` tilbake i
hentestedets lokale klokketid. Feltet er `null` når det ikke er planlagt noe hentevindu.

## Logg over statusoppdateringer

Hver forsendelse har en `status_updates`-liste – alle livssyklushendelser logistikkleverandøren
har rapportert, med den eldste først. Hver oppføring inneholder:

* `state` – hendelsen i statusvokabularet for forsendelser (`pending`, `in_transit`, `delivered`,
  `fault`), slik at du kan lese en tidslinje uten å kjenne transportørens koder. `null` når hendelsen
  ikke har noen status (opprettelse av etikett, en skanning uten informasjon fra transportøren, oppføringer registrert før
  feltet fantes). Aldri `cancelled` – en kansellering er vår, ikke en hendelse fra transportøren.
* `code` – transportørens egen statuskode (GO! sine `GO10`, `GO90`, `GOY001`; DHLs `VA`, `ZF`,
  `LA`, `ZU`). `null` når transportøren ikke oppga noen. Stabil på tvers av språkoversettelser av
  `status`.
* `detail_code` – transportørens mer detaljerte kode der den finnes: DHLs `statusDetailed`, f.eks.
  `CNRFC_NRQRD_ZF` (omdirigert til et postkontor), `HLDCC_SERPT_LA` (klar til henting der),
  `DLVRD_SERPT_ZU` (hentet). `null` ellers.
* `status` – transportørens lesbare tekst (f.eks. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` – en forklaring av koden, eller transportørens lengre setning. `null` når
  ingen av delene finnes.
* `location` – hvor skanningen skjedde, slik transportøren navngir det: et GO!-depot, en DHL-by. Fri
  tekst, ikke et koordinat.
* `time` – ISO 8601-tidsstempel for hendelsen, slik det rapporteres av transportøren (med tidssoneforskyvning).

Når transportøren sender pakken tilbake til avsenderen, får tidslinjen én oppføring med `code`
`RETURNED_TO_SENDER`. `status` inneholder transportørens begrunnelse. Forsendelsen forblir da `fault`, også
etter at transportøren leverer pakken tilbake til oss.

Listen kan være tom hvis transportøren ikke har rapportert noen hendelser ennå.

Bruk toppnivåfeltet `status` for den gjeldende hovedstatusen. Den beveger seg én vei – `pending`
til `in_transit` til `delivered` – med `fault` lagt over så lenge den nyeste hendelsen rapporterer en feil;
transportører sorterer ikke hendelsene etter betydning (DHL legger til en `pre-transit`-kodet omdirigeringsmelding
etter overleveringsskanningen), så den nyeste oppføringen alene sier ikke hvor en pakke befinner seg.

## 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å hjemmetestpakker

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` returnerer testsettet på vei til pasienten og prøven på vei tilbake, som et par:

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

Returraden finnes fra det øyeblikket returetiketten skrives ut, og forblir `pending` til pasienten sender prøven – det er den reelle statusen, ikke et hull.


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