Naar hoofdinhoud gaan
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 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 en Annuleren; 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, Annuleren, Afspraken koppelen en Afspraken ontkoppelen 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 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 / Zending ophalen) 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 / Afspraken van zending ontkoppelen. 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:
Elke statuswijziging verstuurt een shipment.*-webhook, 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.

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

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