Naar hoofdinhoud gaan
POST
Vraag een thuistestkitbestelling aan voor een patiëntprofiel. Een thuistestkitbestelling verzendt een doe-het-zelftestkit per post — Aniva stuurt de kit naar het bezorgadres, de patiënt neemt thuis zelf een monster af en stuurt het per post terug. Dit verschilt van een afspraak, wat een veneuze bloedafname op een testlocatie is. Er is precies één panel vereist. Een thuistestkit komt 1:1 overeen met een fysiek kitproduct — het panel is de kit — en de bestelling komt direct na het aanmaken in de inpakwachtrij, dus de samenstelling moet vooraf definitief zijn. Je kunt het panel nog wijzigen via Thuistestkitbestelling bijwerken zolang de bestelling pending is.

Vervangende kits

Als een kit geen resultaten kan opleveren — de patiënt kon het buisje niet vullen, het monster kwam met te weinig materiaal aan, het laboratorium kon het niet analyseren — bestel dan een vervanging door replaces_home_kit_order_id mee te sturen. Een vervanging is een nieuwe bestelling met een nieuwe labcode, ook als 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. De bestelling die je vervangt blijft ongewijzigd — die behoudt zijn eigen status, zijn eigen labcode en alle resultaten die er al onder zijn vastgelegd. Daaruit volgen twee dingen:
  • Het panel wordt overgenomen. Laat panel_id weg en de vervanging krijgt het panel van de bestelling die wordt vervangen, wat de patiënt heeft gekocht en hoe de doos is bedrukt.
  • Je 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 dit weg om het hele panel opnieuw te testen.
Markers worden opnieuw getest in de groepen van het panel, niet één voor één. Als je één marker uit een groep opgeeft, wordt die hele groep opnieuw getest, omdat een laboratoriumaanvraag die meer rapporteert dan gevraagd niet kan worden geplaatst. Een vervanging voor één marker kan daarom meer dan één resultaat opleveren, en het aantal buisjes kan groter zijn dan de markerlijst doet vermoeden. Er mag maar één vervanging per kit tegelijk onderweg zijn.
Als je hebt geïntegreerd voordat deze velden bestonden, leest Aniva ook metadata.original_kit_id en metadata.replacement_reason bij het aanmaken en behandelt de bestelling als een vervanging. Dit is de enige plek waar metadata wordt geïnterpreteerd, het bestaat alleen om die eerdere integratie te ondersteunen, en de velden hierboven hebben altijd voorrang. Stuur de velden mee.
Een 201 betekent dat de bestelling is vastgelegd en wordt overgedragen aan fulfilment — je hoeft niets anders meer te doen om de kit te laten inpakken en verzenden. Vereist de scope home_kit_orders_manage. Stuur een optionele Idempotency-Key-header mee om het aanmaken veilig opnieuw te kunnen proberen — bij herhaling van dezelfde sleutel krijg je de oorspronkelijke respons terug in plaats van een tweede aan te maken. Zie Idempotentie.

Verzoek

Bodyparameters

string
vereist
UUID van het patiëntprofiel waarvoor de thuistestkitbestelling wordt aangemaakt.
string
vereist
UUID van het cataloguspanel om te bestellen. Precies één — een thuistestkit komt 1:1 overeen met een fysiek kitproduct, dus het panel is de kit. Panel-ID’s worden door Aniva verstrekt voor je partneraccount; zie Panels weergeven. Optioneel bij een vervanging, waarbij standaard het panel wordt gebruikt van de bestelling die je vervangt.
string
UUID van de thuistestkitbestelling die deze vervangt. Door dit mee te sturen wordt dit een vervangende kit — zie Vervangende kits hierboven. De bestelling moet bij hetzelfde profiel horen en mag nog geen vervanging onderweg hebben.
string
Waarom de vervanging nodig is, in één zin (bijvoorbeeld Zu wenig Material, HbA1c nicht auswertbar). Vereist wanneer je replaces_home_kit_order_id meestuurt, en wordt anders genegeerd. Maximaal 500 tekens.
integer[]
Bij een vervanging de markers die het laboratorium opnieuw test — meestal de markers die de eerste kit niet kon opleveren. Elke marker moet deel uitmaken van wat de bestelling die je vervangt heeft aangevraagd; controleer dit met Biomarkers weergeven met home_kit=true. Laat dit weg om het hele panel opnieuw te testen. Alleen geaccepteerd samen met replaces_home_kit_order_id, en niet samen met een andere panel_id. Hiervoor is geen extra scope nodig: markers opnieuw testen waar de patiënt al voor heeft betaald is geen à-la-carteselectie.
object
Je eigen key/value-paren, die bij elke leesactie letterlijk worden teruggegeven en nooit door Aniva worden geïnterpreteerd. Gebruik dit om je eigen bestelreferentie mee te geven zodat je gegevens kunt koppelen zonder onze ID’s op te slaan. Maximaal 20 keys; keys 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; 16.384 bytes geserialiseerd in totaal. Keys die beginnen met aniva_ zijn gereserveerd. Zet nooit persoonlijke of klinische gegevens in metadata — dit wordt niet als patiëntgegevens behandeld.
string[]
Maximaal 5 adressen die elk één e-mail krijgen zodra alle labresultaten definitief zijn. De e-mail linkt naar de resultatenpagina in het Aniva-adminpanel. Je sleutel heeft results_view-toegang tot de patiënt nodig, anders volgt 403. Laat dit veld weg om de standaardadressen van de groep van de patiënt te gebruiken. Een lege lijst zet de e-mails uit. Zie E-mails wanneer resultaten klaarstaan.
object
vereist
Het adres waarnaar de kit wordt verzonden — 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 terminologie als de locations-API). Geef er precies één 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.

Respons

Bij succes retourneert de API 201 Created met de nieuwe thuistestkitbestelling.
string
vereist
Unieke identifier (UUID) van de thuistestkitbestelling.
string
vereist
UUID van het profiel waarbij deze thuistestkitbestelling hoort.
string
vereist
Huidige status van de thuistestkitbestelling. Een van pending, dispatched, activated of cancelled. Een nieuw aangemaakte bestelling start in pending.
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 velden als de locations-API). Geef precies één vorm op — een locatieverwijzing of een inline adres, niet beide.
object
vereist
De key/value-paren die je hebt meegegeven. Altijd aanwezig — {} als je er geen hebt ingesteld.
string
De thuistestkitbestelling die deze vervangt. null bij een normale bestelling.
string
De reden die je hebt opgegeven. null bij een normale bestelling.
string[]
vereist
E-mailadressen die elk één e-mail krijgen zodra alle labresultaten definitief zijn, in kleine letters. Leeg wanneer uitgeschakeld. Zie E-mails bij beschikbare resultaten.
string
Monstercode van het laboratorium waaronder de resultaten worden gerapporteerd — afgedrukt op de fysieke kit, en wat de patiënt van de doos afleest als activeringscode. null totdat de kit is verpakt. Alleen-lezen.
string
vereist
Tijdstip van afname gemeld via Activeren. null totdat de kit is geactiveerd.
string
vereist
ISO 8601-tijdstempel waarop de thuistestkitbestelling is aangemaakt.
string
ISO 8601-tijdstempel van de laatste update. Kan null zijn.
object
vereist
Het patiëntprofiel dat bij deze thuistestkitbestelling hoort.
HomeKitOrderPanel[]
vereist
Het panel dat aan deze thuistestkitbestelling is gekoppeld — het panel dat je als panel_id hebt opgegeven, voorzien van het aanmaaktijdstip van de bestelling. Altijd precies één. Zoek panelgegevens (naam, biomarkers) op via Panels weergeven.
HomeKitOrderIndividualBiomarker[]
vereist
Biomarkers die buiten het panel zijn toegevoegd. Leeg bij normaal aanmaken — thuistestkitbestellingen worden per panel besteld, en om deze lijst achteraf te wijzigen is de capability-scope home_kit_orders_individual_biomarker_selection vereist. Bij een vervanging bevat dit de biomarker_ids die je hebt meegestuurd, die het laboratorium opnieuw test.
HomeKitOrderShipmentLink[]
vereist
Pakketten die aan deze thuistestkitbestelling zijn gekoppeld, met de oudste koppeling eerst. Altijd leeg bij aanmaken — lees de volledige pakketten uit met Zendingen weergeven en ?home_kit_order_id=.

Foutresponsen