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 uitdestination.booked_by— wie het label heeft afgedrukt:anivaofexternal. Alleenaniva-zendingen accepteren Bijwerken en Annuleren; eenexternal-pakket wordt in dezelfde lijst gevolgd, maar geeft bij beide501terug.
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.
appointmentsenhome_kit_ordersvermelden 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
403terug 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 zetsynced_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 metlocation_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.
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 metPATCH /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.
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 metDELETE /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.
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, geeft409 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 veldenorigin en destination in de response van de zending bevatten uitgewerkte adresobjecten met de volgende structuur:
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 veldpickup 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 eenstatus_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.nullals de gebeurtenis geen status heeft (aanmaken van het label, een scan zonder informatie van de vervoerder, vermeldingen van voordat het veld bestond). Nooitcancelled— een annulering komt van ons, niet van de vervoerder.code— de eigen statuscode van de vervoerder (GO10,GO90,GOY001van GO!;VA,ZF,LA,ZUvan DHL).nullals de vervoerder er geen heeft meegegeven. Blijft gelijk ongeacht de taal vanstatus.detail_code— de specifiekere code van de vervoerder als die bestaat:statusDetailedvan DHL, bijv.CNRFC_NRQRD_ZF(doorgestuurd naar een postkantoor),HLDCC_SERPT_LA(klaar om daar op te halen),DLVRD_SERPT_ZU(opgehaald). Andersnull.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.nullals 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).
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:
pending totdat de patiënt het monster op de post doet — dat is de werkelijke status, geen gat.