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

# Zendingen

> Hoe logistiek werkt in de Aniva API: monsterzendingen naar het lab en pakketten met thuistestkits, met tracking en status.

Een zending is één fysiek pakket: een koeriersophaling met bloedmonsters van een testlocatie naar een laboratorium, de kit op weg naar een thuistestkitpatiënt of het monster dat die patiënt terugstuurt. Met de Shipments API kun je verzendopdrachten aanmaken, volgen, wijzigen en annuleren, en zie je elk pakket op één plek, ongeacht wie het heeft geboekt.

## Eén lijst, gefilterd

`GET /api/v1/shipments` is de enige collectie. Een zending staat op zichzelf — deze heeft een veel-op-veelrelatie met afspraken en kan bij een thuistestkitbestelling horen — dus er is geen lijst genest onder een bovenliggend object. Filter dezelfde lijst met `?appointment_id=` of `?home_kit_order_id=`, pagineer deze met `limit` / `offset`, en volg de inline `shipments`-array van een bovenliggend object (`{ id, added_at }` op zowel afspraken als thuistestkitbestellingen) naar [Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md) wanneer je één ID hebt.

## Inhoud, en wie het heeft geboekt

Elke zending bevat twee gegevens die niet uit de adressen blijken:

* `contents` — vrije tekst die beschrijft wat er in het pakket zit, ingesteld bij het aanmaken (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) en getoond aan de koerier. Alleen ter informatie. Richting is geen veld: of een pakket onderweg is naar een laboratorium lees je af uit `destination`.
* `booked_by` — wie het label heeft afgedrukt: `aniva` of `external`. Alleen `aniva`-zendingen accepteren [Bijwerken](https://docs.anivahealth.com/nl/api/shipments/update-shipment.md) en [Annuleren](https://docs.anivahealth.com/nl/api/shipments/cancel-shipment.md); een `external`-pakket wordt in dezelfde lijst gevolgd, maar geeft bij beide `501` terug.

Een pakket met een retourlabel en het pakket dat met dat label terugkomt, verwijzen naar elkaar via `paired_with`.

## Toegang

* Je kunt een pakket inzien wanneer minstens één gekoppelde afspraak of thuistestkitbestelling binnen jouw toegangscontext valt, of wanneer het is vertrokken vanaf een locatie binnen jouw toegangscontext.
* `appointments` en `home_kit_orders` vermelden alleen de afspraken en bestellingen binnen jouw toegangscontext.
* Voor [Bijwerken](https://docs.anivahealth.com/nl/api/shipments/update-shipment.md), [Annuleren](https://docs.anivahealth.com/nl/api/shipments/cancel-shipment.md), [Afspraken koppelen](https://docs.anivahealth.com/nl/api/shipments/attach-appointments-to-shipment.md) en [Afspraken ontkoppelen](https://docs.anivahealth.com/nl/api/shipments/detach-appointments-from-shipment.md) moet elke gekoppelde thuistestkitbestelling binnen jouw toegangscontext vallen. Anders geeft de aanroep `403` terug en kan alleen Aniva het pakket wijzigen.

## Leesverzoeken roepen nooit de vervoerder aan

Elk leesverzoek wordt vanuit onze database beantwoord. Een achtergrondsynchronisatie werkt elke zending bij met de vervoerder (elke 10 minuten voor GO!, elk uur voor DHL) en zet `synced_at`, waarmee je ziet hoe oud het antwoord is. Er is geen geforceerde verversing — DHL staat één trackingaanroep per vijf seconden toe, dus een leesverzoek dat direct de vervoerder bevraagt kan niet worden aangeboden.

## Een zending aanmaken

Bij het aanmaken van een zending geef je de herkomst op met `location_id` — de testlocatie waar de koerier moet ophalen. Je geeft ook het bestemmingslaboratorium op met `destination_lab`. De zending gaat naar het geregistreerde verzendadres van dat laboratorium.

De locatie moet binnen de toegangscontext van je API-sleutel vallen. Gebruik [Locaties weergeven](https://docs.anivahealth.com/nl/api/locations/list-locations.md) om beschikbare locatie-ID's te vinden.

Je kunt optioneel `appointment_id` meegeven om de zending bij het aanmaken aan een specifieke afspraak
te koppelen. De koppeling verschijnt inline aan beide kanten:

* op de zending, als een `appointments`-array van `{ id, added_at }`-items;
* op de afspraak, als een `shipments`-array van `{ id, added_at }`-items.

Beide arrays staan op volgorde van oudste koppeling eerst. Elke `id` verwijst naar het canonieke detail-endpoint
([Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md) /
[Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md)) voor de volledige payload — partners die
per afspraak de voortgang van de koerier willen volgen, volgen elk item in de `shipments`-array van de afspraak naar
het detail-endpoint van de zending.

Een zending kan aan meerdere afspraken worden gekoppeld, en een afspraak kan aan meerdere
zendingen worden gekoppeld. Beheer de koppeling na het aanmaken met [Afspraken aan
zending koppelen](https://docs.anivahealth.com/nl/api/shipments/attach-appointments-to-shipment.md) /
[Afspraken van zending ontkoppelen](https://docs.anivahealth.com/nl/api/shipments/detach-appointments-from-shipment.md). Elke
mutatie geeft de bijgewerkte afsprakenlijst van de zending terug.

De mutatieregel is: koppelingen kunnen worden aangemaakt of verwijderd wanneer OFWEL de afspraak voorbij
de bloedafname is (`blood_drawn`), OF de zending minder dan 24 uur geleden is aangemaakt. Buiten dat
tijdvenster is de koppeling vergrendeld zodat historische gegevens stabiel blijven.

## Levenscyclus

Zendingen doorlopen de volgende statussen:

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

| Status | Betekenis |
| - | - |
| `pending` | De koeriersopdracht is geplaatst en wacht op ophalen. |
| `in_transit` | De koerier heeft het pakket opgehaald en het is onderweg. |
| `delivered` | Het pakket is bezorgd. |
| `fault` | Er is een probleem opgetreden tijdens het transport, of de vervoerder heeft het pakket teruggestuurd naar de afzender. |
| `cancelled` | De zending is geannuleerd. |

Elke statuswijziging verstuurt een `shipment.*`-[webhook](https://docs.anivahealth.com/nl/concepts/webhooks.md), bijvoorbeeld
`shipment.delivered`. `shipment.updated` wordt geactiveerd bij elke wijziging die je kunt lezen, zoals een nieuwe scan.

## Regels voor het ophaalschema

De volgende regels gelden bij het aanmaken of bijwerken van het ophaalschema van een zending. `pickup_date`
(`YYYY-MM-DD`) en `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24-uurs) zijn lokale tijden
**geïnterpreteerd in de IANA-tijdzone van de vertreklocatie** — je stuurt er geen tijdzone bij mee.

| Regel | Detail |
| - | - |
| **Alleen werkdagen** | `pickup_date` moet maandag–vrijdag zijn. |
| **Vandaag of toekomst** | `pickup_date` mag niet in het verleden liggen. |
| **Sluitingstijd vandaag** | Ophalen op dezelfde dag wordt na 16:00 Europe/Berlin geweigerd. |
| **Tijdbereik** | `pickup_time_from` en `pickup_time_till` moeten binnen 09:00–19:00 liggen. |
| **Venster van minimaal 2 uur** | Het ophaalvenster moet minimaal 2 uur duren. |

## Zendingen wijzigen

Je kunt het ophaalschema, aantal pakketten, gewicht en de opmerkingen van een zending bijwerken met `PATCH /api/v1/shipments/{id}`. Als logistiek relevante velden wijzigen (ophaaldatum, tijd, aantal pakketten of gewicht), wordt de bestaande logistieke opdracht automatisch geannuleerd en wordt een nieuwe aangemaakt. Velden die je weglaat uit de update-body blijven behouden van de bestaande zending — als je bijvoorbeeld alleen `weight` bijwerkt, wordt de opdracht opnieuw aangemaakt met hetzelfde ophaalschema. Bijgewerkte schemavelden worden gevalideerd aan de hand van dezelfde [regels voor het ophaalschema](#regels-voor-het-ophaalschema).

> [!WARNING]
>
> Zendingen kunnen niet meer worden gewijzigd nadat de koerier het pakket heeft opgehaald. Pogingen om een
> zending met de status `in_transit`, `delivered` of `fault` bij te werken, geven `409 Conflict` terug.

Als de logistieke dienstverlener de annulering of het opnieuw aanmaken tijdens een update weigert, geeft de API `502 Bad Gateway` terug met de foutmelding van de dienstverlener.

## Zendingen annuleren

Annuleer een zending met `DELETE /api/v1/shipments/{id}`. Dit roept de API van de logistieke dienstverlener aan om de opdracht te annuleren en werkt de status bij naar `cancelled`.

> [!WARNING]
>
> Zendingen kunnen na het ophalen niet meer worden geannuleerd. Pogingen om een zending te annuleren die al
> `in_transit`, `delivered` of `fault` is, geven `409 Conflict` terug. Een zending annuleren die al
> `cancelled` is, is een no-op die `200` met de zending teruggeeft — zie
> [Idempotentie](https://docs.anivahealth.com/nl/concepts/idempotency.md).

De logistieke dienstverlener kan de annulering ook om eigen redenen weigeren (bijv. als de annuleringsdeadline is verstreken). In dat geval geeft de API `502 Bad Gateway` terug met de foutmelding en foutcode van de dienstverlener.

### Retourlabels

Een DHL-retourlabel maakt deel uit van de uitgaande opdracht. DHL kan het label niet afzonderlijk annuleren, dus het annuleren van de rij die een retourlabel volgt, geeft `409 Conflict` terug. Annuleer in plaats daarvan het uitgaande pakket terwijl het `pending` is. Daarmee wordt het label ook geannuleerd: elke `pending` retourrij van het uitgaande pakket wordt `cancelled` en krijgt een `RETURN_LEG_CANCELLED`-vermelding in `status_updates`. Een retourpakket dat de patiënt al op de post heeft gedaan, blijft onderweg. Nadat het uitgaande pakket is verzonden, blijft het label geldig en sluit Aniva de retourrij handmatig.

## Referentie-ID's van zendingen

Elke zending heeft een referentie-ID van 11 tekens: een letter, de datum en vier tekens, `{letter}YYMMDDXXXX` (bijvoorbeeld `P2611194821`). De letter geeft aan waar de zending bij hoort, nooit de richting:

| Letter | Zending |
| - | - |
| `P` | Een zending die je via deze API aanmaakt. |
| `M` | Een zending die het Aniva-team aanmaakt. |
| `C` | Een zending van Aniva's dagelijkse verzending. |
| `K` | Een pakket met een thuiskit. |
| `F`, `S` | Aniva's eigen voorraadpakketten. |

Een zending van 20 tot en met 22 november 2026 behoudt het ID met een woord ervoor: `API`, `MAN`, `AUTO` of `KIT` (bijvoorbeeld `AUTO261121UWKX`). Beide vormen blijven geldig. Controleer niet de lengte of de eerste letter van een ID. Gebruik het ID om de zending op te halen, bij te werken of te annuleren.

## Adressen van zendingen

De velden `origin` en `destination` in de response van de zending bevatten uitgewerkte adresobjecten met de volgende structuur:

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

Voor een praktijkpakket wordt het `origin`-adres afgeleid van de testlocatie die je bij het
aanmaken hebt opgegeven en is `destination` het laboratorium dat je in `destination_lab` hebt genoemd.
Voor een thuistestpakket is het bezorgadres van de patiënt de `destination` van de kit en de
`origin` van de retourzending van het monster; de locatie die de kit inpakt is de `origin` ervan. Het
adres bevat geen `location_id` — herleid een praktijkpakket via de afspraak waaraan het is
gekoppeld.

## Ophaalvenster

Het veld `pickup` in de response van de zending bevat het geplande ophaalvenster van de koerier. Het
bevat `from`- en `till`-tijdstempels als UTC-tijdstippen (ISO 8601 met `Z`-achtervoegsel, bijv.
`2026-04-15T07:00:00Z`) en een `timezone`-string (IANA-tijdzone van de ophaallocatie). De
lokale `pickup_date` / `pickup_time_*` die je bij het aanmaken of bijwerken hebt meegestuurd, wordt met die tijdzone omgezet naar deze
absolute tijdstippen — gebruik `timezone` om `from` / `till` weer in de lokale tijd van de
ophaallocatie weer te geven. Het veld is `null` als er geen ophaalvenster is gepland.

## Logboek van statusupdates

Elke zending bevat een `status_updates`-array — elke levenscyclusgebeurtenis die de logistieke dienstverlener
heeft gemeld, oudste eerst. Elke vermelding bevat:

* `state` — de gebeurtenis in de statussen van de zending (`pending`, `in_transit`, `delivered`,
  `fault`), zodat je een tijdlijn kunt lezen zonder de codes van de vervoerder te kennen. `null` als de gebeurtenis
  geen status heeft (aanmaken van het label, een scan zonder informatie van de vervoerder, vermeldingen van voordat het
  veld bestond). Nooit `cancelled` — een annulering komt van ons, niet van de vervoerder.
* `code` — de eigen statuscode van de vervoerder (`GO10`, `GO90`, `GOY001` van GO!; `VA`, `ZF`,
  `LA`, `ZU` van DHL). `null` als de vervoerder er geen heeft meegegeven. Blijft gelijk ongeacht de taal van
  `status`.
* `detail_code` — de specifiekere code van de vervoerder als die bestaat: `statusDetailed` van DHL, bijv.
  `CNRFC_NRQRD_ZF` (doorgestuurd naar een postkantoor), `HLDCC_SERPT_LA` (klaar om daar op te halen),
  `DLVRD_SERPT_ZU` (opgehaald). Anders `null`.
* `status` — het leesbare label van de vervoerder (bijv. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — een uitleg van de code, of de langere omschrijving van de vervoerder. `null` als
  geen van beide bestaat.
* `location` — waar de scan heeft plaatsgevonden, zoals de vervoerder die noemt: een GO!-depot, een plaats van DHL. Vrije
  tekst, geen coördinaat.
* `time` — ISO 8601-tijdstempel van de gebeurtenis, zoals gemeld door de vervoerder (met tijdzone-offset).

Als de vervoerder het pakket terugstuurt naar de afzender, krijgt de tijdlijn één vermelding met `code`
`RETURNED_TO_SENDER`. In `status` staat de reden van de vervoerder. De zending blijft dan `fault`, ook
nadat de vervoerder het pakket weer bij ons heeft bezorgd.

De lijst kan leeg zijn als de vervoerder nog geen gebeurtenissen heeft gemeld.

Gebruik het `status`-veld op het hoogste niveau voor de geldende huidige status. Die beweegt in één richting — van `pending`
naar `in_transit` naar `delivered` — met `fault` erbovenop zolang de nieuwste gebeurtenis een fout meldt;
vervoerders ordenen hun gebeurtenissen niet op belang (DHL voegt na de overdrachtsscan nog een omleidingsbericht
met de code `pre-transit` toe), dus alleen de nieuwste vermelding zegt niet waar een pakket zich bevindt.

## Voorbeeldzending

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

## Voorbeeld van thuistestpakketten

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` geeft de kit op weg naar de patiënt en het retourmonster samen als paar terug:

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

De retourrij bestaat vanaf het moment dat het retourlabel wordt afgedrukt en blijft `pending` totdat de patiënt het monster op de post doet — dat is de werkelijke status, geen gat.


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