Naar hoofdinhoud gaan
Een thuistestkitbestelling stuurt een testkit voor zelfafname per post naar een patiënt. Aniva verzendt de kit, de patiënt neemt thuis zelf een monster af en stuurt het per post terug. Dit verschilt van een afspraak, waarbij een zorgverlener een veneuze bloedafname doet op een fysieke testlocatie.
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

string
vereist
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.
string
vereist
De UUID van het profiel waarbij deze thuistestkitbestelling hoort.
string
vereist
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.
object
vereist
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.
string
vereist
ISO 8601-tijdstempel waarop de thuistestkitbestelling is aangemaakt.
string
ISO 8601-tijdstempel van de meest recente update. Null als de thuistestkitbestelling nog nooit is bijgewerkt.
object
Het volledige profielobject van de patiënt, ingebed in elke response van een thuistestkitbestelling.
object[]
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.
object[]
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.
string
De thuistestkitbestelling die door deze bestelling wordt vervangen, wanneer het een vervangende kit is. null bij een normale bestelling.
string
Waarom de vervanging is verzonden, in één zin. null bij een normale bestelling.
string[]
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.
object
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.
string
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=….
string
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.
object[]
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

Wat je terugkrijgt, hangt af van de kit. Een bloedkit levert twee zendingen op zodra Aniva hem heeft ingepakt: het pakket van Aniva naar de patiënt en het pakket van de patiënt naar het laboratorium (de 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.
De samenstelling van een thuistestkit-bestelling kan alleen worden gewijzigd zolang deze op pending staat. Zodra de bestelling dispatched is (of verder — activated/cancelled), geven panelwissels en de /biomarkers-endpoints 409 Conflict terug: de fysieke kit wordt ingepakt op basis van het gekozen panel, dus de inhoud ligt vast zodra hij naar de patiënt vertrekt. Moet je toch de tests op een al vergrendelde bestelling wijzigen, neem dan rechtstreeks contact op met Aniva — meestal is het nog mogelijk, en we voeren de wijziging voor je door zodat de inhoud van de kit blijft kloppen. Is de kit al gebruikt en kon hij geen resultaten opleveren, bestel dan in plaats daarvan een vervangende kit.

Thuistestkit-bestellingen ophalen

Haal alle thuistestkit-bestellingen op waartoe je API-sleutel toegang heeft:
Geef optioneel ?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:
Geef de 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:
Een vervanging is een nieuwe bestelling met een nieuwe labcode, ook wanneer de eerste kit nooit is geactiveerd: het laboratorium heeft een nieuwe aanvraag nodig, en twee monsters onder één code zijn niet uit elkaar te houden. Beide bestellingen blijven leesbaar en zijn gekoppeld via 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.
Er mag maar één vervanging per kit tegelijk onderweg zijn — zolang een vervanging 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:
Neem alleen de velden op die je wilt wijzigen. 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:
Hiermee wordt de status van de thuistestkit-bestelling op 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 op pending.
  • 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.
Een annulering die een fout teruggeeft laat de bestelling precies zoals deze was, dus alleen een 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:
Geef 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 een individual_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):
Biomarkers verwijderen (idempotent — een ID dat niet is gekoppeld, wordt genegeerd):
Beide endpoints accepteren een 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:
De response bevat geplande tests (status 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.

Voorbeeld van een thuistestkit-bestelling