Endpoints voor thuistestkitbestellingen vereisen de scope
home_kit_orders_view (lezen) of
home_kit_orders_manage (schrijven). Activeren
accepteert ook de beperktere scope home_kit_orders_activate.
Resultaten ophalen en
Resultaten e-mailen vereisen daarnaast results_view —
labresultaten en documenten zijn daar altijd mee afgeschermd.Velden
UUID die automatisch door Aniva is gegenereerd. Gebruik deze om de bestelling bij te werken, het
panel te wisselen, te activeren, te annuleren en resultaten op te halen.
Huidige levenscyclusstatus. Een van
pending, dispatched, activated of cancelled. Zie
Levenscyclus hieronder. De gedetailleerde voltooiingsstatus van labresultaten
(in_progress vs. completed) wordt afgeleid uit
Resultaten ophalen.Het adres waar de kit naartoe wordt gestuurd — in een van twee vormen: ofwel
{location_id} dat
verwijst naar een bekende testlocatie, ofwel de inline adresvelden (name, street, city,
postal_code, country_code; company_name / house_number / address_line_2 / state /
phone / email optioneel — dezelfde veldnamen als in de locations-API). Geef precies één vorm
op — een locatieverwijzing of een inline adres, niet beide.Packstation of Postfiliale (alleen Duitsland): stel
street in op Packstation of
Postfiliale, house_number op het driecijferige stationsnummer en address_line_2 op het
DHL Postnummer van de ontvanger (6–10 cijfers, spaties toegestaan). Zonder het Postnummer kan
het pakket niet worden geboekt. Een Postfach wordt niet ondersteund.ISO 8601-tijdstempel van de meest recente update. Null als de thuistestkitbestelling nog nooit is
bijgewerkt.
Het volledige profielobject van de patiënt, ingebed in elke response van een
thuistestkitbestelling.
Het panel dat aan de thuistestkitbestelling is gekoppeld — altijd precies één item met
{ panel_id, added_at }, omdat een thuistestkit 1:1 overeenkomt met een fysiek kitproduct. Zoek
de panel_id op via Panels opvragen.Biomarkers die buiten het panel om aan de thuistestkitbestelling zijn gekoppeld. Elk item is
{ biomarker_id, added_at }. Zoek elke biomarker_id op via
Biomarkers opvragen met home_kit=true. Bij een normale
bestelling zijn dit losse tests boven op het panel; bij een vervangende kit
zijn dit de tests die het laboratorium opnieuw uitvoert.De thuistestkitbestelling die door deze bestelling wordt vervangen, wanneer het een
vervangende kit is.
null bij een normale bestelling.E-mailadressen die elk één e-mail krijgen zodra alle labresultaten definitief zijn, in kleine
letters. Altijd aanwezig — leeg als dit uitstaat. Stel dit in via
Aanmaken of
Bijwerken. Zie
E-mails bij voltooide resultaten.
Je eigen sleutel-waardeparen, letterlijk teruggegeven en nooit geïnterpreteerd door Aniva. Altijd
aanwezig bij uitlezen —
{} als je niets hebt ingesteld. Maximaal 20 sleutels; sleutels voldoen
aan [A-Za-z0-9_-] en zijn maximaal 40 tekens lang; waarden zijn een string, getal of boolean,
waarbij strings maximaal 500 tekens lang zijn; in totaal maximaal 16.384 bytes geserialiseerd.
Sleutels die beginnen met aniva_ zijn gereserveerd. Bij
Bijwerken wordt metadata samengevoegd: sleutels die je
weglaat blijven behouden, een sleutel met waarde null wordt verwijderd en {} wist alles.
Validatie is alles-of-niets. Zet nooit persoonlijke of klinische gegevens in metadata — dit wordt
niet als patiëntgegevens behandeld.De monstercode van het laboratorium. Eén code, drie rollen: de code waaronder labresultaten worden
gerapporteerd, de code die op de fysieke kit is afgedrukt en de activeringscode die de patiënt van
de doos afleest. Toegewezen wanneer de kit wordt ingepakt —
null zolang de bestelling pending
is, behalve nadat Aniva een kit opnieuw heeft verzonden (zie Levenscyclus). Altijd
alleen-lezen. Koppel een fysieke kit terug aan de bijbehorende bestelling met
GET /api/v1/home-kit-orders?lab_code=….Het afnametijdstip dat is doorgegeven via Activeren —
wanneer de patiënt het monster daadwerkelijk heeft afgenomen, als UTC-tijdstip.
null totdat de
kit is geactiveerd. Dit is het afnametijdstip dat op het labrapport staat.De pakketten die aan deze bestelling zijn gekoppeld, oudste koppeling eerst, elk met
{ id, added_at } — de kit op weg naar de patiënt en, voor kits waarvan de retourzending wordt
gevolgd, het monster op weg terug naar het laboratorium, zichtbaar zodra de labels worden
afgedrukt. Leeg zolang de bestelling pending is, behalve nadat Aniva een kit opnieuw heeft
verzonden. Lees de volledige pakketten in één aanroep uit met
GET /api/v1/shipments?home_kit_order_id={id} — zie Zendingen.Levenscyclus
Thuistestkitbestellingen hebben vier levenscyclusstatussen:
Wanneer Aniva een verloren kit opnieuw verstuurt, gaat de bestelling terug naar
pending, maar blijven de lab_code en de
eerdere pakketten in shipments behouden. De nieuwe kit krijgt dezelfde code. Er gaat een ongebruikt retourlabel mee in
de nieuwe doos. Alleen Aniva voert deze twee overgangen uit; de API biedt ze niet aan. Elke overgang verstuurt een
home_kit_order.pending- of home_kit_order.cancelled-webhook.
De statussen van een thuistestkit-bestelling zijn bewust grof gehouden. De bezorgvoortgang naar en van de
patiënt wordt bijgehouden op de zendingen van de bestelling —
dispatched betekent dat de kit
een label en een labcode heeft, niet dat hij al onderweg is; de status van de uitgaande zending geeft aan of dat zo
is. De verwerking van labresultaten loopt via inzendingen. Of de labresultaten compleet zijn (in_progress versus
completed) zie je via Resultaten ophalen — het top-level
status-veld is in_progress totdat elke inzending is afgerond, en daarna completed — of fault wanneer
elke inzending is mislukt zonder resultaten te melden.De pakketten volgen
destination is het lab), gekoppeld via paired_with. Het
retourpakket blijft op pending staan — met het trackingnummer al bekend — totdat de patiënt het op de post
doet. Een darmmicrobioomkit levert één zending op: de kit naar de patiënt. De retourenvelop is
gefrankeerd en heeft geen track & trace, dus er wordt niets geboekt voor de terugweg. booked_by geeft aan wie het
label heeft geboekt: "aniva" of "external". Alleen een "aniva"-pakket kan hier worden gewijzigd, en alleen de
notes zodra het label is geprint. Elk pakket bevat de volledige status_updates van de vervoerder,
inclusief de detail_code van DHL voor een omleiding naar een postkantoor.
home_kit_orders op de zending vermeldt alleen de bestellingen binnen je toegangscontext. Zie
Toegang.
Thuistestkit-bestellingen ophalen
Haal alle thuistestkit-bestellingen op waartoe je API-sleutel toegang heeft:?profile_id={uuid} mee om op een specifiek profiel te filteren, of ?lab_code={code} om
een fysieke kit in handen te koppelen aan de bijbehorende bestelling — de logische eerste stap van een activatieflow.
Een thuistestkit-bestelling aanmaken
Vraag een thuistestkit-bestelling aan voor een patiëntprofiel:profile_id, een delivery_address en één panel_id mee. De bestelling wordt aangemaakt met de status pending.
Geef optioneel een Idempotency-Key-header mee zodat een nieuwe poging geen tweede kit bestelt — zie Idempotentie.
Precies één panel, omdat een thuistestkit 1:1 overeenkomt met een fysiek kitproduct — het panel is de kit. Alleen panels die Aniva als thuistestkit heeft geconfigureerd zijn te bestellen; elk ander panel wordt geweigerd met 422. Het is verplicht bij het aanmaken, omdat de bestelling direct in de inpakwachtrij komt en het inpakken meteen kan beginnen. Zolang de bestelling op pending staat, kun je het panel wisselen via Bijwerken.
Om een tweede kit te sturen voor een kit die geen resultaten kon opleveren, geef je replaces_home_kit_order_id mee in plaats van een panel te kiezen — zie Vervangende kits.
Vervangende kits
Soms kan een kit geen resultaten opleveren: de patiënt kreeg het buisje niet vol, het monster kwam aan met te weinig materiaal, het laboratorium kon een deel ervan niet analyseren. Bestel er een vervanging voor:replaces_home_kit_order_id.
De bestelling die je vervangt blijft ongewijzigd. Deze behoudt zijn status, zijn labcode en alle resultaten die er al onder zijn vastgelegd, zodat een patiënt die de eerste kit alsnog op de post doet alles krijgt wat het laboratorium eruit kan lezen.
Het panel wordt overgenomen. Laat panel_id weg en de vervanging krijgt het panel van de bestelling die wordt vervangen — dat is wat de patiënt heeft gekocht en hoe de doos is vormgegeven. Stuur alleen een ander panel mee voor een vervanging van het hele panel; een panel en een subset van markers samen worden geweigerd met 422, omdat een subset alleen betekenis heeft binnen het panel waaruit die is gekozen. Het panel van een vervanging kan achteraf ook niet worden gewisseld.
Jij kiest wat opnieuw wordt getest. Stuur biomarker_ids mee met de markers die zijn mislukt en het laboratorium test alleen die opnieuw, zodat de kit alleen de benodigde buisjes bevat. Laat het veld weg om het hele panel opnieuw te testen — de juiste keuze als er helemaal niets is geanalyseerd. Hiervoor is geen extra scope nodig: markers opnieuw testen waarvoor de patiënt al heeft betaald, is geen à-la-carteselectie. Die markers kunnen achteraf niet worden verwijderd, omdat ze de volledige aanvraag vormen.
Markers worden opnieuw getest als de groepen van het panel, niet één voor één. Als je één marker uit een groep noemt, wordt
die hele groep opnieuw getest, omdat een laboratoriumaanvraag die meer rapporteert dan is aangevraagd niet kan worden
geplaatst. Een vervanging voor één enkele marker kan daarom meer dan één resultaat opleveren, en
het aantal buisjes kan groter zijn dan de lijst met markers doet vermoeden.
pending of dispatched is, geeft een tweede aanmaakverzoek voor dezelfde bestelling 409 terug met een verwijzing naar die vervanging. Resultaten komen binnen onder de eigen lab_code van de vervanging, via Resultaten ophalen voor die vervanging.
Een vervanging is niet bedoeld voor een pakket dat nooit is aangekomen. Laat het in plaats daarvan aan Aniva weten: dat is een nieuwe verzending van dezelfde bestelling onder dezelfde labcode, geen nieuwe bestelling.
Een thuistestkit-bestelling bijwerken
Wijzig het bezorgadres, wissel het panel, werk je metadata bij of vervang de e-mailadressen voor de resultatenmelding:panel_id vervangt het gekoppelde panel — met precies één panel per kit is wisselen de enige zinvolle panelbewerking, daarom zijn er geen endpoints om panels toe te voegen of te verwijderen. Het adres en het panel kunnen alleen worden gewijzigd zolang de status pending is; metadata blijft beschrijfbaar gedurende de hele levensduur van de bestelling. results_ready_emails blijft beschrijfbaar totdat de bestelling cancelled is.
Een thuistestkit-bestelling annuleren
Annuleer een thuistestkit-bestelling die niet meer nodig is:cancelled gezet. De geannuleerde thuistestkit-bestelling wordt teruggegeven in de respons.
Alleen een bestelling met de status pending kan worden geannuleerd. Vanaf dispatched is de kit ingepakt en gelabeld — automatisch terughalen is niet mogelijk — en geeft de aanroep 409 terug. Als een kit die al is verzonden moet worden tegengehouden, neem dan rechtstreeks contact op met Aniva.
Als je een bestelling met de status pending annuleert waarvan de kit al bij fulfilment is besteld, wordt deze daar ook geannuleerd, en de aanroep slaagt alleen als fulfilment akkoord gaat:
409— de kit was al ingepakt en gelabeld en kan dus niet meer worden teruggehaald, ook al staat de bestelling nog oppending.502— fulfilment heeft de annulering geweigerd (de foutmelding bevat hun reden) of was niet bereikbaar. Er is niets gewijzigd — de bestelling is nog actief en kan opnieuw worden geannuleerd.
200 bevestigt dat er geen kit komt.
Het annuleren van een bestelling die al cancelled is geeft dezelfde 200 terug, ongeacht vanuit welke status deze is geannuleerd.
Een thuistestkit-bestelling activeren
Wanneer de patiënt het monster heeft afgenomen, meld je dit:activated_at mee — het moment waarop de patiënt het monster daadwerkelijk heeft afgenomen, als UTC-tijdstip. Dit is het afnametijdstip dat op het labrapport komt te staan, dus stuur het echte afnamemoment, niet je verwerkingstijd. Activering is definitief: de bestelling gaat naar activated en kan niet meer worden geannuleerd of gewijzigd. De tegenhanger voor thuiskits van Bloedafname bevestigen, zonder barcode — de code van de kit wordt bij het inpakken aangebracht, dus je hoeft die nooit te weten. De bestelling moet op dat moment zijn lab_code hebben; een bestelling zonder die code geeft 409 terug.
Activeren plaatst ook de laboratoriumaanvraag: het panel van de kit wordt bij het laboratorium aangevraagd onder de bijbehorende lab_code, zodat het teruggestuurde monster wordt verwacht en resultaten worden gekoppeld zodra het laboratorium ze rapporteert. Dit gebeurt na de respons, en een probleem aan de kant van het laboratorium wordt door Aniva afgehandeld in plaats van teruggegeven op je verzoek.
Individuele biomarkers
Je kunt individuele biomarkers toevoegen aan een thuistestkit-bestelling als à-la-cartetests, buiten het panel om. Dit is handig wanneer je een selectie op maat wilt boven op de kit. De toegevoegde biomarkers verschijnen in de respons van de thuistestkit-bestelling als eenindividual_biomarkers-array (op hetzelfde niveau als panels).
Beide biomarker-endpoints vereisen de capability-scope home_kit_orders_individual_biomarker_selection boven op home_kit_orders_manage — thuistestkits worden per panel besteld, dus losse markers worden per partner ingeschakeld. Vraag het aan Aniva als je integratie dit nodig heeft.
Biomarkers toevoegen (idempotent — al gekoppelde biomarkers blijven behouden):
biomarker_ids-array. Gebruik Biomarkers opvragen met home_kit=true om biomarker-ID’s op te zoeken. Biomarkers kunnen alleen worden gewijzigd zolang de kit pending is (zie Levenscyclus).
Labresultaten ophalen
Zodra het lab het teruggestuurde monster heeft verwerkt, haal je de klinische en genetische resultaten op:planned) naast ontvangen resultaten, zodat je kunt bijhouden wat nog openstaat. Resultaten worden vastgelegd onder de lab_code van de bestelling en komen marker voor marker binnen terwijl het lab ze analyseert, dus gedeeltelijke payloads zijn normaal. Het status-veld op het hoogste niveau is in_progress tot het definitieve rapport en daarna completed (of fault als elke labopdracht is mislukt zonder rapportage) — gebruik dit om te bepalen of het labwerk voor de thuistestkit-bestelling klaar is. Een home_kit_order.results.completed-webhook meldt wanneer dat gebeurt, zodat je niet hoeft te pollen. Labrapport-PDF’s staan vermeld in de documents-array — gebruik GET /api/v1/documents/{id} om ze te downloaden.