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

> Zendingen ophalen, gefilterd op afspraak, thuiskitbestelling of status

Haal de zendingen op waartoe je API-sleutel toegang heeft, nieuwste eerst. Elk pakket staat in deze ene lijst:
een koeriersophaling bij een praktijk, de kit onderweg naar een thuistestkitpatiënt en het monster op
de terugweg. Filter op één bovenliggend item met `appointment_id` of `home_kit_order_id`.

Vereist de scope `shipments_view` of `shipments_manage`.

Het antwoord komt uit onze database en roept de vervoerder nooit aan. Een achtergrondsynchronisatie vernieuwt elke
zending (elke 10 minuten voor GO!, elk uur voor DHL) en `synced_at` geeft op elke rij aan wanneer de
vervoerder voor het laatst is bevraagd.

## Verzoek

### Queryparameters

**appointment\_id** `string`

Alleen zendingen gekoppeld aan deze afspraak (UUID). `404` als de afspraak niet bestaat, `403`
als deze buiten je toegangscontext valt.

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

Alleen zendingen gekoppeld aan deze thuistestkitbestelling (UUID). Meestal komen er twee rijen terug — de kit
onderweg naar de patiënt en het monster terug naar het laboratorium (`destination` is het lab). Dezelfde
regels voor `404` / `403` als bij `appointment_id`.

**status** `string`

Alleen zendingen met deze status. Een van `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Maximaal aantal zendingen om terug te geven. Standaard 100, maximaal 500.

**offset** `integer`

Aantal over te slaan zendingen. Standaard 0. De sortering is stabiel (`created_at` aflopend, daarna
referentie), zodat pagina's elkaar niet overlappen.

## Respons

Bij succes geeft de API `200 OK` terug met een array van zendingsobjecten.

**id** `string` *required*

Referentie-identifier van de zending.

**status** `string` *required*

Levenscyclusstatus van de zending. Een van `pending`, `in_transit`, `delivered`, `fault` of `cancelled`.

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

Vervoerder. Een van `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` of `dhl_express`. Een pakket met een thuistestkit is `dhl_parcel`, of `dhl_warenpost` wanneer het naar het buitenland gaat
als Warenpost International.

**tracking\_number** `string`

Extern trackingnummer van de vervoerder. Kan `null` zijn.

**contents** `string`

Vrije tekstbeschrijving van de inhoud van het pakket, zoals opgegeven bij het aanmaken (bijv. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Alleen ter informatie — of een pakket naar een
laboratorium gaat lees je af uit `destination`, en de tegenhanger ervan uit `paired_with`. Kan `null` zijn.

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

Wie het verzendlabel heeft afgedrukt: `aniva` of `external`. Alleen zendingen van `aniva` ondersteunen
[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 gevolgd, maar geeft bij beide `501` terug.

**paired\_with** `string`

Referentie van het andere pakket in een zending van twee pakketten — het pakket met een
retourlabel en het pakket dat met dat label terugkomt. Ingesteld op beide. `null` bij een enkel pakket.

**origin** `object`

Ophaaladres. Kan `null` zijn.

**adresobject**

**name** `string` *required*

Naam van ontvanger, bedrijf of locatie.

**company\_name** `string`

Bedrijf / p/a-regel. Kan `null` zijn.

**street** `string` *required*

Straatnaam, zonder huisnummer.

**house\_number** `string`

Huisnummer. Kan `null` zijn.

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

Gebouw, ingang of verdieping. Kan `null` zijn.

**city** `string` *required*

Plaats.

**state** `string`

Staat of provincie. Kan `null` zijn.

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

Postcode.

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

ISO 3166-1 alpha-2-landcode.

**phone** `string`

Telefoonnummer voor contact. Kan `null` zijn.

**email** `string`

E-mailadres voor contact. Kan `null` zijn.

**destination** `object`

Bezorgadres. Zelfde structuur als `origin`. Kan `null` zijn.

**pickup** `object`

Gepland ophaalvenster. Kan `null` zijn.

**pickup-object**

**from** `string` *required*

Begin van het ophaalvenster als UTC-tijdstip (ISO 8601 met `Z`-achtervoegsel).

**till** `string` *required*

Einde van het ophaalvenster als UTC-tijdstip (ISO 8601 met `Z`-achtervoegsel).

**timezone** `string` *required*

IANA-tijdzone van de ophaallocatie (bijv. `Europe/Berlin`). Gebruik deze om `from` / `till` weer te geven in de lokale tijd van de ophaallocatie.

**notes** `string`

Optionele notities. Kan `null` zijn.

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

Chronologische gebeurtenissen in de levenscyclus van de logistieke partner (oudste eerst). Lege array als de
aanbieder nog geen gebeurtenissen heeft gemeld. Gebruik dit voor weergave per gebeurtenis, audit en gedetailleerdere signalen van de vervoerder;
vertrouw op `status` voor de definitieve actuele status.

**velden voor statusupdates**

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

De gebeurtenis in de termen voor zendingstatussen — `pending`, `in_transit`, `delivered` of
`fault` — zodat je een tijdlijn kunt lezen zonder de codes van de vervoerder te kennen. `null` wanneer de
gebeurtenis geen status bevat (aanmaken van een label, een scan zonder informatie van de vervoerder, meldingen die zijn vastgelegd
voordat dit veld bestond). Nooit `cancelled`.

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

De eigen statuscode van de vervoerder: `GO10` / `GO90` / `GOY001` van GO!, `VA` / `ZF` / `LA`
/ `ZU` van DHL. `null` wanneer de vervoerder er geen heeft meegegeven. Blijft gelijk bij vertalingen van
`status`.

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

De gedetailleerdere code van de vervoerder als die er is — `statusDetailed` van DHL, bijv. `CNRFC_NRQRD_ZF`
(doorgestuurd naar een postkantoor), `HLDCC_SERPT_LA` (daar klaar voor afhalen), `DLVRD_SERPT_ZU`
(afgehaald). `null` voor vervoerders zonder deze code.

**status** `string` *required*

Statuslabel van de vervoerder (vrije tekst, bijv. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

Een uitleg van de code of de langere zin van de vervoerder. `null` als geen van beide bestaat.

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

Waar de scan plaatsvond, zoals de vervoerder dat noemt — een depot van GO! (`"HUB Niederaula"`) of een
stad bij DHL. Vrije tekst, geen coördinaat. `null` als de vervoerder niets heeft gemeld.

**time** `string` *required*

Tijdstip waarop de gebeurtenis is waargenomen (ISO 8601, met de tijdzone-offset die de vervoerder meldde).

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

Afspraken gekoppeld aan deze zending, oudste koppeling eerst. Elk item heeft de vorm `{ id, added_at }`;
haal elke `id` op via [Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md) voor de
volledige gegevens van de afspraak. Lege array als er geen afspraken zijn gekoppeld.
Alleen de afspraken binnen je toegangscontext worden weergegeven.

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

Thuistestkitbestellingen gekoppeld aan deze zending, oudste koppeling eerst, in dezelfde vorm `{ id, added_at }`.
Haal elke `id` op via [Thuistestkitbestelling ophalen](https://docs.anivahealth.com/nl/api/home-kit-orders/get-home-kit.md). Lege
array voor praktijkpakketten. Alleen de bestellingen binnen je toegangscontext worden weergegeven. Zie
[Toegang](https://docs.anivahealth.com/nl/concepts/shipments.md#toegang).

**synced\_at** `string`

Wanneer de zending voor het laatst met de vervoerder is gesynchroniseerd, als UTC-tijdstip. Leesverzoeken roepen de
vervoerder nooit aan — een achtergrondsynchronisatie houdt zendingen actueel — dus dit geeft aan hoe oud het antwoord is. `null` tot
de eerste synchronisatie.

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

Tijdstempel van aanmaken (ISO 8601).

**updated\_at** `string`

Tijdstempel van laatste update (ISO 8601). Kan `null` zijn.

## Herhaalde aanroepen

Aniva slaat het antwoord van dit endpoint 5 minuten op per API-sleutel. Een herhaalde aanroep binnen
deze tijd krijgt het opgeslagen antwoord. De headers `Cache-Status` en `Age` laten zien dat het antwoord is
opgeslagen en hoe oud het is.

Abonneer je op de webhook-gebeurtenissen `shipment.created` en `shipment.updated` om direct op de hoogte te zijn van wijzigingen.
Zie [Herhaalde leesverzoeken](https://docs.anivahealth.com/nl/concepts/webhooks.md#herhaalde-leesverzoeken).

## Foutresponsen

| Status | Beschrijving |
| - | - |
| `400` | Ongeldige queryparameter. |
| `403` | Verboden — ontbrekende scope, of de gefilterde afspraak of thuistestkitbestelling valt buiten je scope. |
| `404` | De gefilterde afspraak of thuistestkitbestelling is niet gevonden. |
| `500` | Interne serverfout. |

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