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

# Försändelser

> Så fungerar logistiken i Aniva API: provförsändelser till labbet och paket med hemtestkit, med spårning och status.

En försändelse är ett fysiskt paket: en budhämtning med blodprover från en provtagningsplats till ett laboratorium, kitet på väg till en patient med hemtestkit eller provet som patienten postar tillbaka. Shipments-API:et låter dig skapa, spåra, ändra och avboka försändelser, och listar alla paket på ett ställe oavsett vem som bokade dem.

## En lista, filtrerad

`GET /api/v1/shipments` är den enda samlingen. En försändelse står för sig själv — den har en många-till-många-relation med bokningar och kan höra till en beställning av hemtestkit — så det finns ingen lista kapslad under ett överordnat objekt. Begränsa samma lista med `?appointment_id=` eller `?home_kit_order_id=`, paginera den med `limit` / `offset` och följ den inbäddade `shipments`-arrayen (`{ id, added_at }` på både bokningar och beställningar av hemtestkit) till [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md) när du har ett id.

## Innehåll och vem som bokade

Varje försändelse innehåller två uppgifter som inte framgår av adresserna:

* `contents` — fritext som beskriver vad som finns i paketet, anges vid skapandet (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) och visas för budet. Endast för information. Riktning är inte ett fält: om ett paket är på väg till ett laboratorium framgår av `destination`.
* `booked_by` — vem som skrev ut etiketten: `aniva` eller `external`. Endast `aniva`-försändelser accepterar [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 i samma lista men returnerar `501` på båda.

Ett paket som innehöll en returetikett och paketet som etiketten skickar tillbaka pekar på varandra via `paired_with`.

## Åtkomst

* Du kan läsa ett paket när minst en kopplad bokning eller beställning av hemtestkit finns i din åtkomstkontext, eller när det skickades från en plats i din åtkomstkontext.
* `appointments` och `home_kit_orders` listar bara de bokningar och beställningar som finns i din åtkomstkontext.
* [Uppdatera](https://docs.anivahealth.com/sv/api/shipments/update-shipment.md), [Avboka](https://docs.anivahealth.com/sv/api/shipments/cancel-shipment.md), [Koppla bokningar](https://docs.anivahealth.com/sv/api/shipments/attach-appointments-to-shipment.md) och [Koppla bort bokningar](https://docs.anivahealth.com/sv/api/shipments/detach-appointments-from-shipment.md) kräver att varje kopplad beställning av hemtestkit finns i din åtkomstkontext. Annars returnerar anropet `403`, och bara Aniva kan ändra paketet.

## Läsningar anropar aldrig transportören

Varje läsning besvaras från vår databas. En bakgrundssynkronisering stämmer av varje försändelse mot dess transportör (var 10:e minut för GO!, varje timme för DHL) och sätter `synced_at`, som visar hur gammalt ett svar är. Det finns ingen tvingad uppdatering — DHL tillåter ett spårningsanrop var femte sekund, så en läsning som anropar transportören direkt kan inte erbjudas.

## Skapa en försändelse

När du skapar en försändelse anger du avsändarens `location_id` — provtagningsplatsen där budet ska hämta upp. Du anger också mottagande laboratorium med `destination_lab`. Försändelsen skickas till laboratoriets registrerade leveransadress.

Platsen måste ingå i din API-nyckels åtkomstkontext. Använd [Lista platser](https://docs.anivahealth.com/sv/api/locations/list-locations.md) för att hitta tillgängliga plats-ID:n.

Du kan valfritt skicka med `appointment_id` för att koppla försändelsen till en specifik bokning vid
skapandet. Kopplingen visas direkt på båda sidor:

* på försändelsen, som en `appointments`-array med `{ id, added_at }`-poster;
* på bokningen, som en `shipments`-array med `{ id, added_at }`-poster.

Båda arrayerna har den äldsta kopplingen först. Varje `id` korsrefererar till den kanoniska detalj-endpointen
([Hämta bokning](https://docs.anivahealth.com/sv/api/appointments/get-appointment.md) /
[Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md)) för hela payloaden — partner som vill
följa budets status per bokning följer varje post i bokningens `shipments`-array till
försändelsens detalj-endpoint.

En försändelse kan kopplas till flera bokningar, och en bokning kan kopplas till flera
försändelser. Efter skapandet hanterar du kopplingen med [Koppla bokningar till
försändelse](https://docs.anivahealth.com/sv/api/shipments/attach-appointments-to-shipment.md) /
[Koppla bort bokningar från försändelse](https://docs.anivahealth.com/sv/api/shipments/detach-appointments-from-shipment.md). Varje
ändring returnerar försändelsens uppdaterade bokningslista.

Ändringsregeln är: kopplingar kan skapas eller tas bort när ANTINGEN bokningen har passerat
blodprovstagning (`blood_drawn`), eller försändelsen skapades för mindre än 24 timmar sedan. Utanför det
fönstret är kopplingen låst så att historiska poster förblir stabila.

## Livscykel

Försändelser går igenom följande statusar:

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

| Status | Betydelse |
| - | - |
| `pending` | Budbeställningen har lagts och väntar på upphämtning. |
| `in_transit` | Budet har hämtat paketet och det är på väg. |
| `delivered` | Paketet har levererats. |
| `fault` | Ett problem uppstod under transporten, eller transportören skickade tillbaka paketet till avsändaren. |
| `cancelled` | Försändelsen har avbokats. |

Varje statusändring skickar en `shipment.*`-[webhook](https://docs.anivahealth.com/sv/concepts/webhooks.md), till exempel
`shipment.delivered`. `shipment.updated` utlöses vid varje ändring du kan läsa av, som en ny skanning.

## Regler för upphämtningsschema

Följande regler gäller när du skapar eller uppdaterar en försändelses upphämtningsschema. `pickup_date`
(`YYYY-MM-DD`) och `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24-timmarsformat) är lokala tider
som **tolkas i avsändarplatsens IANA-tidszon** – du skickar inte med någon tidszon tillsammans med dem.

| Regel | Detalj |
| - | - |
| **Endast vardagar** | `pickup_date` måste vara måndag–fredag. |
| **I dag eller framåt** | `pickup_date` kan inte ligga i det förflutna. |
| **Stopptid samma dag** | Upphämtning samma dag nekas efter 16:00 Europe/Berlin. |
| **Tidsintervall** | `pickup_time_from` och `pickup_time_till` måste ligga inom 09:00–19:00. |
| **Minst 2 timmars fönster** | Upphämtningsfönstret måste vara minst 2 timmar långt. |

## Ändra försändelser

Du kan uppdatera en försändelses upphämtningsschema, antal paket, vikt och anteckningar med `PATCH /api/v1/shipments/{id}`. Om något logistikrelevant fält ändras (upphämtningsdatum, tid, antal paket eller vikt) avbokas den befintliga logistikbeställningen automatiskt och en ny skapas. Fält som du utelämnar i uppdateringsbegäran behålls från den befintliga försändelsen – om du till exempel bara uppdaterar `weight` skapas beställningen på nytt med samma upphämtningsschema. Uppdaterade schemafält valideras mot samma [regler för upphämtningsschema](#regler-foer-upphaemtningsschema).

> [!WARNING]
>
> Försändelser kan inte ändras efter att budet har hämtat paketet. Försök att uppdatera en
> försändelse med status `in_transit`, `delivered` eller `fault` ger `409 Conflict`.

Om logistikleverantören avvisar avbokningen eller nybeställningen vid en uppdatering returnerar API:et `502 Bad Gateway` med leverantörens felmeddelande.

## Avboka försändelser

Avboka en försändelse med `DELETE /api/v1/shipments/{id}`. Detta anropar logistikleverantörens API för att avboka beställningen och uppdaterar statusen till `cancelled`.

> [!WARNING]
>
> Försändelser kan inte avbokas efter upphämtning. Försök att avboka en försändelse som redan har
> status `in_transit`, `delivered` eller `fault` ger `409 Conflict`. Att avboka en som redan är
> `cancelled` gör ingenting och returnerar `200` med försändelsen – se
> [Idempotens](https://docs.anivahealth.com/sv/concepts/idempotency.md).

Logistikleverantören kan också avvisa avbokningen av egna skäl (t.ex. om tidsfristen för avbokning har passerat). I så fall returnerar API:et `502 Bad Gateway` med leverantörens felmeddelande och felkod.

### Returetiketter

En returetikett från DHL är en del av den utgående beställningen. DHL kan inte makulera etiketten på egen hand; att avboka raden som spårar en returetikett ger därför `409 Conflict`. Avboka det utgående paketet i stället, medan det är `pending`. Då makuleras etiketten samtidigt: varje returrad med status `pending` för det utgående paketet blir `cancelled` och får en `RETURN_LEG_CANCELLED`-post i sin `status_updates`. Ett returpaket som patienten redan har skickat fortsätter på sin väg. När det utgående paketet har skickats fortsätter etiketten att gälla och Aniva stänger returraden manuellt.

## Referens-ID:n för försändelser

Varje försändelse har ett referens-ID på 11 tecken: en bokstav, datumet och fyra tecken, `{letter}YYMMDDXXXX` (till exempel `P2611194821`). Bokstaven visar vad försändelsen tillhör, aldrig dess riktning:

| Bokstav | Försändelse |
| - | - |
| `P` | En försändelse som du skapar via detta API. |
| `M` | En försändelse som Aniva-teamet skapar. |
| `C` | En försändelse i Anivas dagliga utskick. |
| `K` | Ett paket med hemkit. |
| `F`, `S` | Anivas egna lagerpaket. |

En försändelse från 20 till 22 november 2026 behåller sitt ID med ett ord framför: `API`, `MAN`, `AUTO` eller `KIT` (till exempel `AUTO261121UWKX`). Båda formaten förblir giltiga. Kontrollera inte längden eller den första bokstaven i ett ID. Använd ID:t för att hämta, uppdatera eller avbryta försändelsen.

## Adresser för försändelser

Fälten `origin` och `destination` i försändelsesvaret innehåller uppslagna adressobjekt med följande 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"
}
```

För ett mottagningspaket hämtas `origin`-adressen från den testplats du angav när försändelsen
skapades, och `destination` är det laboratorium du angav i `destination_lab`.
För ett hemtestpaket är patientens leveransadress `destination` för kitet och
`origin` för provreturen; platsen som packar kitet är dess `origin`. Adressen
innehåller inget `location_id` – koppla ett mottagningspaket via den bokning det är
knutet till.

## Upphämtningsfönster

Fältet `pickup` i försändelsesvaret innehåller det schemalagda upphämtningsfönstret för budet. Det
innehåller tidsstämplarna `from` och `till` som UTC-tidpunkter (ISO 8601 med suffixet `Z`, t.ex.
`2026-04-15T07:00:00Z`) och en `timezone`-sträng (upphämtningsplatsens IANA-tidszon). De
lokala värdena `pickup_date` / `pickup_time_*` som du skickade när försändelsen skapades eller
uppdaterades räknas om till dessa absoluta tidpunkter med hjälp av den tidszonen – använd `timezone`
för att visa `from` / `till` i upphämtningsplatsens lokala tid igen. Fältet är `null` när inget
upphämtningsfönster har schemalagts.

## Logg över statusuppdateringar

Varje försändelse har en `status_updates`-array – alla livscykelhändelser som logistikleverantören
har rapporterat, äldst först. Varje post innehåller:

* `state` – händelsen i försändelsens statusvokabulär (`pending`, `in_transit`, `delivered`,
  `fault`), så att du kan läsa en tidslinje utan att känna till transportörens koder. `null` när
  händelsen saknar status (etikett skapad, en skanning utan information från transportören, poster
  som registrerades innan fältet fanns). Aldrig `cancelled` – en avbokning är vår, inte en
  händelse från transportören.
* `code` – transportörens egen statuskod (`GO10`, `GO90`, `GOY001` hos GO!; `VA`, `ZF`,
  `LA`, `ZU` hos DHL). `null` när transportören inte skickade någon. Stabil över olika
  språköversättningar av `status`.
* `detail_code` – 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` (uthämtad). `null` i övriga fall.
* `status` – transportörens läsbara text (t.ex. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` – en förklaring av koden, eller transportörens längre beskrivning. `null` när
  ingetdera finns.
* `location` – var skanningen skedde, så som transportören anger det: en GO!-depå, en stad hos
  DHL. Fritext, inte en koordinat.
* `time` – ISO 8601-tidsstämpel för händelsen, så som transportören rapporterade den (med sin
  tidsförskjutning).

När transportören skickar tillbaka paketet till avsändaren får tidslinjen en post med `code`
`RETURNED_TO_SENDER`. Dess `status` innehåller transportörens orsak. Försändelsen förblir sedan
`fault`, även efter att transportören har levererat tillbaka paketet till oss.

Listan kan vara tom om transportören inte har rapporterat några händelser ännu.

Använd toppnivåfältet `status` för aktuell gällande status. Den rör sig åt ett håll – `pending`
till `in_transit` till `delivered` – med `fault` överlagrat medan den senaste händelsen rapporterar
ett fel; transportörer sorterar inte sina händelser efter betydelse (DHL lägger till en avisering
om omdirigering med koden `pre-transit` efter överlämningsskanningen), så den senaste posten ensam
säger inte var ett paket befinner sig.

## Exempelförsändelse

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

## Exempel på hemtestpaket

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` returnerar kitet på väg till patienten och provet på väg tillbaka, ihopparade:

```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 finns från det ögonblick returetiketten skrivs ut och förblir `pending` tills patienten skickar provet – det är det verkliga läget, inte en lucka.


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